                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          domain 
name and port for your provider. Call ehlo() and starttls(), and then call 
login() and pass it your email address and sys.argv[1], which will store your 
password string. You’ll enter the password as a command line argument 
each time you run the program, to avoid saving your password in your 
source code. 

Once your program has logged in to your email account, it should go 
through the unpaidMembers dictionary and send a personalized email to each 
member’s email address. Add the following to sendDuesReminders.py: 





#! python3 
# sendDuesReminders.py - Sends emails based on payment status in spreadsheet. 


--snip-- 


# Send out reminder emails. 
for name, email in unpaidMembers.items(): 

body = "Subject: %s dues unpaid.\nDear %s,\nRecords show that you have not 
paid dues for %s. Please make this payment as soon as possible. Thank you!'" % 
(latestMonth, name, latestMonth) 

print('Sending email to %s...' % email) 

sendmailStatus = smtp0bj.sendmail('my email_address@gmail.com', email, body) 


if sendmailStatus != {}: 
print('There was a problem sending email to %s: %s' % (email, 
sendmailStatus) ) 
smtpObj.quit() 





This code loops through the names and emails in unpaidMembers. For 
each member who hasn’t paid, we customize a message with the latest month 
and the member’s name, and store the message in body ®. We print output 
saying that we’re sending an email to this member’s email address @. Then 
we call sendmail(), passing it the from address and the customized message ®. 
We store the return value in sendmailStatus. 

Remember that the sendmail() method will return a nonempty diction- 
ary value if the SMTP server reported an error sending that particular 
email. The last part of the for loop at @ checks if the returned dictionary is 
nonempty, and if it is, prints the recipient’s email address and the returned 
dictionary. 

After the program is done sending all the emails, the quit() method is 
called to disconnect from the SMTP server. 

When you run the program, the output will look something like this: 





Sending email to alice@example.com... 
Sending email to bob@example.com... 
Sending email to eve@example.com... 





The recipients will receive an email that looks like Figure 16-3. 
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June 2014 dues unpaid. Inbox x 
Ẹ Al Sweigart <asweigart@gmail.com> 
to me |» 


Dear Alice 
Records show that you have not paid dues for June 2014. Please make this payment as soon as possible. Thank you! 








Figure 16-3: An automatically sent email from sendDuesReminders.py 


Sending Text Messages with Twilio 
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Most people are more likely to be near their phones than their computers, 
so text messages can be a more immediate and reliable way of sending noti- 
fications than email. Also, the short length of text messages makes it more 
likely that a person will get around to reading them. 

In this section, you’ll learn how to sign up for the free Twilio service and 
use its Python module to send text messages. Twilio is an SMS gateway service, 
which means it’s a service that allows you to send text messages from your 
programs. Although you will be limited in how many texts you can send per 
month and the texts will be prefixed with the words Sent from a Twilio trial 
account, this trial service is probably adequate for your personal programs. 
The free trial is indefinite; you won't have to upgrade to a paid plan later. 

Twilio isn’t the only SMS gateway service. If you prefer not to use Twilio, 
you can find alternative services by searching online for free sms gateway, 
python sms api, or even twilio alternatives. 

Before signing up for a Twilio account, install the twilio module. 
Appendix A has more details about installing third-party modules. 


This section ts specific to the United States. Twilio does offer SMS texting services for 
countries outside of the United States, but those specifics aren't covered in this book. 
The twilio module and its functions, however, will work the same outside the United 
States. See http://twilio.com/ for more information. 


Signing Up for a Twilio Account 


Go to hitp://twilio.com/ and fill out the sign-up form. Once you've signed up 
for a new account, you'll need to verify a mobile phone number that you 
want to send texts to. (This verification is necessary to prevent people from 
using the service to spam random phone numbers with text messages.) 

After receiving the text with the verification number, enter it into the 
Twilio website to prove that you own the mobile phone you are verifying. You 
will now be able to send texts to this phone number using the twilio module. 

Twilio provides your trial account with a phone number to use as the 
sender of text messages. You will need two more pieces of information: 
your account SID and the auth (authentication) token. You can find this 
information on the Dashboard page when you are logged in to your Twilio 
account. These values act as your Twilio username and password when log- 
ging in from a Python program. 





Sending Text Messages 


Once you've installed the twilio module, signed up for a Twilio account, ver- 
ified your phone number, registered a Twilio phone number, and obtained 
your account SID and auth token, you will finally be ready to send yourself 
text messages from your Python scripts. 

Compared to all the registration steps, the actual Python code is fairly 
simple. With your computer connected to the Internet, enter the following 
into the interactive shell, replacing the accountSID, authToken, myTwilioNumber, 
and myCellPhone variable values with your real information: 





>>> from twilio.rest import TwilioRestClient 

>>> accountSID = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXAXX! 

>>> authToken = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' 

>>> twilioCli = TwilioRestClient(accountSID, authToken) 

>>> myTwilioNumber = '+14955551234' 

>>> myCellPhone = '+14955558888' 

>>> message = twilioCli.messages.create(body='Mr. Watson - Come here - I want 
to see you.', from_=myTwilioNumber, to=myCellPhone) 





A few moments after typing the last line, you should receive a text mes- 
sage that reads Sent from your Twilio trial account - Mr. Watson - Come here - I 
want to see you. 

Because of the way the twilio module is set up, you need to import 
it using from twilio.rest import TwilioRestClient, not just import twilio O. 
Store your account SID in accountSID and your auth token in authToken and 
then call TwilioRestClient() and pass it accountSID and authToken. The call to 
TwilioRestClient() returns a TwilioRestClient object @. This object has a mes- 
sages attribute, which in turn has a create() method you can use to send text 
messages. This is the method that will instruct Twilio’s servers to send your 
text message. After storing your Twilio number and cell phone number in 
myTwilioNumber and myCellPhone, respectively, call create() and pass it keyword 
arguments specifying the body of the text message, the sender’s number 
(myTwilioNumber), and the recipient’s number (myCellPhone) ®. 

The Message object returned from the create() method will have infor- 
mation about the text message that was sent. Continue the interactive shell 
example by entering the following: 





>>> message.to 

"414955558888 ' 

>>> message. from_ 

"+14955551234' 

>>> message.body 

"Mr. Watson - Come here - I want to see you.' 





The to, from_, and body attributes should hold your cell phone number, 
Twilio number, and message, respectively. Note that the sending phone 
number is in the from_attribute—with an underscore at the end—not from. 
This is because from is a keyword in Python (you’ve seen it used in the from 
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modulename import * form of import statement, for example), so it cannot be 
used as an attribute name. Continue the interactive shell example with 
the following: 


>>> message.status 

"queued' 

>>> message.date_created 
datetime.datetime(2015, 7, 8, 1, 36, 18) 
>>> message.date_sent == None 

True 





The status attribute should give you a string. The date_created and 
date_sent attributes should give you a datetime object if the message has been 
created and sent. It may seem odd that the status attribute is set to 'queued' 
and the date_sent attribute is set to None when you've already received the 
text message. This is because you captured the Message object in the message 
variable before the text was actually sent. You will need to refetch the Message 
object in order to see its most up-to-date status and date_sent. Every Twilio 
message has a unique string ID (SID) that can be used to fetch the latest 
update of the Message object. Continue the interactive shell example by 
entering the following: 





>>> message.sid 

' SM09520de7639ba3af137c6fcb7c5f4b51' 

>>> updatedMessage = twilioCli.messages.get(message.sid) 
>>> updatedMessage.status 

'delivered' 

>>> updatedMessage.date_sent 

datetime.datetime(2015, 7, 8, 1, 36, 18) 





Entering message.sid show you this message’s long SID. By passing this 
SID to the Twilio client’s get() method @, you can retrieve a new Message 
object with the most up-to-date information. In this new Message object, the 
status and date_sent attributes are correct. 

The status attribute will be set to one of the following string values: 
‘queued’, ‘sending’, 'sent', 'delivered', 'undelivered', or 'failed'. These sta- 
tuses are self-explanatory, but for more precise details, take a look at the 
resources at hitp://nostarch.com/automatestuff/. 


RECEIVING TEXT MESSAGES WITH PYTHON 


Unfortunately, receiving text messages with Twilio is a bit more complicated 


than sending them. Twilio requires that you have a website running its own 


web application. That’s beyond the scope of this book, but you can find more 
details in the resources for this book (http://nostarch.com/automatestuff/). 





Project: “Just Text Me” Module 


000 


The person yov’ll most often text from your programs is probably you. 
Texting is a great way to send yourself notifications when you’re away from 
your computer. If you’ve automated a boring task with a program that takes 
a couple of hours to run, you could have it notify you with a text when it’s 
finished. Or you may have a regularly scheduled program running that 
sometimes needs to contact you, such as a weather-checking program that 
texts you a reminder to pack an umbrella. 

As a simple example, here’s a small Python program with a textmyself() 
function that sends a message passed to it as a string argument. Open a 
new file editor window and enter the following code, replacing the account 
SID, auth token, and phone numbers with your own information. Save it as 
textMyself-py. 





#! python3 
# textMyself.py - Defines the textmyself() function that texts a message 
# passed to it as a string. 


# Preset values: 

accountSID = 'ACXxxxxXXXXXXXXXXXXXXXXXXXXXXXXXXXX | 
authToken = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX | 
myNumber = '+15559998888' 

twilioNumber = '+15552225678' 


from twilio.rest import TwilioRestClient 


def textmyself (message): 
twilioCli = TwilioRestClient(accountSID, authToken) 
twilioCli.messages.create(body=message, from _=twilioNumber, to=myNumber) 


This program stores an account SID, auth token, sending number, and 
receiving number. It then defined textmyself() to take on argument @, make 
a TwilioRestClient object @, and call create() with the message you passed ®. 

If you want to make the textmyself() function available to your other 
programs, simply place the textMyself-py file in the same folder as the Python 
executable (C:\Python34 on Windows, /usr/local/lib/python3.4 on OS X, and 
/usr/bin/python3 on Linux). Now you can use the function in your other 
programs. Whenever you want one of your programs to text you, just add the 
following: 





import textmyself 
textmyself.textmyself('The boring task is finished.') 





You need to sign up for Twilio and write the texting code only once. 
After that, it’s just two lines of code to send a text from any of your other 
programs. 
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Summary 


We communicate with each other on the Internet and over cell phone net- 
works in dozens of different ways, but email and texting predominate. Your 
programs can communicate through these channels, which gives them 
powerful new notification features. You can even write programs running 
on different computers that communicate with one another directly via 
email, with one program sending emails with SMTP and the other retriev- 
ing them with IMAP. 

Python’s smtplib provides functions for using the SMTP to send 
emails through your email provider’s SMTP server. Likewise, the third- 
party imapclient and pyzmail modules let you access IMAP servers and 
retrieve emails sent to you. Although IMAP is a bit more involved than 
SMTP, it’s also quite powerful and allows you to search for particular 
emails, download them, and parse them to extract the subject and body 
as string values. 

Texting is a bit different from email, since, unlike email, more than 
just an Internet connection is needed to send SMS texts. Fortunately, ser- 
vices such as Twilio provide modules to allow you to send text messages 
from your programs. Once you go through an initial setup process, you'll 
be able to send texts with just a couple lines of code. 

With these modules in your skill set, you'll be able to program the spe- 
cific conditions under which your programs should send notifications or 
reminders. Now your programs will have reach far beyond the computer 
they’re running on! 


Practice Questions 
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1. What is the protocol for sending email? For checking and receiving 
email? 


2. What four smtplib functions/methods must you call to log in to an 
SMTP server? 


3. What two imapclient functions/methods must you call to log in to an 
IMAP server? 

4. What kind of argument do you pass to imapObj.search()? 

5. What do you do if your code gets an error message that says got more 
than 10000 bytes? 


6. The imapclient module handles connecting to an IMAP server and find- 
ing emails. What is one module that handles reading the emails that 
imapclient collects? 


7. What three pieces of information do you need from Twilio before you 
can send text messages? 


Practice Projects 


For practice, write programs that do the following. 


Random Chore Assignment Emailer 


Write a program that takes a list of people’s email addresses and a list 
of chores that need to be done and randomly assigns chores to people. 
Email each person their assigned chores. If you’re feeling ambitious, keep 
a record of each person’s previously assigned chores so that you can make 
sure the program avoids assigning anyone the same chore they did last 
time. For another possible feature, schedule the program to run once a 
week automatically. 

Here’s a hint: If you pass a list to the random.choice() function, it will 
return a randomly selected item from the list. Part of your code could look 
like this: 





chores = ['dishes', ‘bathroom’, ‘vacuum’, ‘walk dog' ] 
randomChore = random.choice(chores) 
chores. remove(randomChore) # this chore is now taken, so remove it 





Umbrella Reminder 


Chapter 11 showed you how to use the requests module to scrape data from 
http://weather.gou/. Write a program that runs just before you wake up in the 
morning and checks whether it’s raining that day. If so, have the program 
text you a reminder to pack an umbrella before leaving the house. 


Auto Unsubscriber 


Write a program that scans through your email account, finds all the unsub- 
scribe links in all your emails, and automatically opens them in a browser. 
This program will have to log in to your email provider’s IMAP server 
and download all of your emails. You can use BeautifulSoup (covered in 
Chapter 11) to check for any instance where the word unsubscribe occurs 
within an HTML link tag. 

Once you have a list of these URLs, you can use webbrowser.open() to 
automatically open all of these links in a browser. 

You'll still have to manually go through and complete any additional 
steps to unsubscribe yourself from these lists. In most cases, this involves 
clicking a link to confirm. 

But this script saves you from having to go through all of your emails 
looking for unsubscribe links. You can then pass this script along to your 
friends so they can run it on their email accounts. (Just make sure your 
email password isn’t hardcoded in the source code!) 
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Controlling Your Computer Through Email 


Write a program that checks an email account every 15 minutes for any 
instructions you email it and executes those instructions automatically. 
For example, BitTorrent is a peer-to-peer downloading system. Using free 
BitTorrent software such as qBittorrent, you can download large media 
files on your home computer. If you email the program a (completely legal, 
not at all piratical) BitTorrent link, the program will eventually check its 
email, find this message, extract the link, and then launch qBittorrent 
to start downloading the file. This way, you can have your home computer 
begin downloads while you're away, and the (completely legal, not at all 
piratical) download can be finished by the time you return home. 

Chapter 15 covers how to launch programs on your computer using the 
subprocess.Popen() function. For example, the following call would launch 
the qBittorrent program, along with a torrent file: 





qbProcess = subprocess.Popen(['C:\\Program Files (x86)\\qBittorrent\\ 
qbittorrent.exe', 'shakespeare_complete_works.torrent' ]) 


Of course, you'll want the program to make sure the emails come from 
you. In particular, you might want to require that the emails contain a pass- 
word, since it is fairly trivial for hackers to fake a “from” address in emails. 
The program should delete the emails it finds so that it doesn’t repeat 
instructions every time it checks the email account. As an extra feature, 
have the program email or text you a confirmation every time it executes 
a command. Since you won’t be sitting in front of the computer that is 
running the program, it’s a good idea to use the logging functions (see 
Chapter 10) to write a text file log that you can check if errors come up. 

qBittorrent (as well as other BitTorrent applications) has a feature 
where it can quit automatically after the download completes. Chapter 15 
explains how you can determine when a launched application has quit with 
the wait() method for Popen objects. The wait() method call will block until 
qBittorrent has stopped, and then your program can email or text you a 
notification that the download has completed. 

There are a lot of possible features you could add to this project. If you 
get stuck, you can download an example implementation of this program 
from hitp://nostarch.com/automatestuff/. 


MANIPULATING IMAGES 


D 
= 
Y 


D K 
haley) 


If you have a digital camera or even if 
you just upload photos from your phone 
to Facebook, you probably cross paths with 
digital image files all the time. You may know 
how to use basic graphics software, such as Microsoft 
Paint or Paintbrush, or even more advanced applica- 





tions such as Adobe Photoshop. But if you need to 
edit a massive number of images, editing them by 
hand can be a lengthy, boring job. 


Enter Python. Pillow is a third-party Python module for interacting 
with image files. The module has several functions that make it easy to 
crop, resize, and edit the content of an image. With the power to manipu- 
late images the same way you would with software such as Microsoft Paint 
or Adobe Photoshop, Python can automatically edit hundreds or thousands 
of images with ease. 


Computer Image Fundamentals 


In order to manipulate an image, you need to understand the basics of how 
computers deal with colors and coordinates in images and how you can 

work with colors and coordinates in Pillow. But before you continue, install 
the pillow module. See Appendix A for help installing third-party modules. 


Colors and RGBA Values 


Computer programs often represent a color in an image as an RGBA value. 
An RGBA value is a group of numbers that specify the amount of red, green, 
blue, and alpha (or transparency) in a color. Each of these component values 
is an integer from 0 (none at all) to 255 (the maximum). These RGBA values 
are assigned to individual pixels; a pixel is the smallest dot of a single color 
the computer screen can show (as you can imagine, there are millions of 
pixels on a screen). A pixel’s RGB setting tells it precisely what shade of 
color it should display. Images also have an alpha value to create RGBA 
values. If an image is displayed on the screen over a background image 
or desktop wallpaper, the alpha value determines how much of the back- 
ground you can “see through” the image’s pixel. 

In Pillow, RGBA values are represented by a tuple of four integer values. 
For example, the color red is represented by (255, 0, 0, 255). This color has 
the maximum amount of red, no green or blue, and the maximum alpha 
value, meaning it is fully opaque. Green is represented by (0, 255, 0, 255), 
and blue is (0, 0, 255, 255). White, the combination of all colors, is (255, 
255, 255, 255), while black, which has no color at all, is (0, 0, 0, 255). 

Ifa color has an alpha value of 0, it is invisible, and it doesn’t really mat- 
ter what the RGB values are. After all, invisible red looks the same as invis- 
ible black. 

Pillow uses the standard color names that HTML uses. Table 17-1 lists a 
selection of standard color names and their values. 


Table 17-1: Standard Color Names and Their RGBA Values 


Name RGBA value Name RGBA value 
White (255, 255, 255, 255) Red (255, 0, 0, 255) 
Green (0, 128, 0, 255) Blue (0, 0, 255, 255) 
Gray (128, 128, 128, 255) Yellow (255, 255, 0, 255) 
Black (0, 0, 0, 255) Purple (128, 0, 128, 255) 


Pillow offers the ImageColor.getcolor() function so you don’t have to 
memorize RGBA values for the colors you want to use. This function takes 
a color name string as its first argument, and the string 'RGBA' as its second 
argument, and it returns an RGBA tuple. 
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CMYK AND RGB COLORING 


In grade school you learned that mixing red, yellow, and blue paints can 


form other colors; for example, you can mix blue and yellow to make green 


paint. This is known as the subtractive color model, and it applies to dyes, inks, 
and pigments. This is why color printers have CMYK ink cartridges: the Cyan 
(blue), Magenta (red), Yellow, and blacK ink can be mixed together to form any 
color. 

However, the physics of light uses what's called an additive color model. 
When combining light (such as the light given off by your computer screen), 
red, green, and blue light can be combined to form any other color. This is why 
RGB values represent color in computer programs. 





To see how this function works, enter the following into the interactive 
shell: 





>>> from PIL import ImageColor 

>>> ImageColor.getcolor('red', 'RGBA') 

(255, 0, 0, 255) 

>>> ImageColor.getcolor('RED', 'RGBA') 

(255, 0, 0, 255) 

>>> ImageColor.getcolor('Black', 'RGBA') 

(0, 0, 0, 255) 

>>> ImageColor.getcolor('chocolate', 'RGBA') 
(210, 105, 30, 255) 

>>> ImageColor.getcolor('CornflowerBlue', ‘RGBA' ) 
(100, 149, 237, 255) 





First, you need to import the ImageColor module from PIL ® (not 
from Pillow; you'll see why in a moment). The color name string you pass 
to ImageColor.getcolor() is case insensitive, so passing 'red' @ and passing 
"RED' ® give you the same RGBA tuple. You can also pass more unusual 
color names, like 'chocolate' and ‘Cornflower Blue’. 

Pillow supports a huge number of color names, from 'aliceblue' to 
‘whitesmoke'. You can find the full list of more than 100 standard color 
names in the resources at http://nostarch.com/automatestuff/. 


Coordinates and Box Tuples 


Image pixels are addressed with x- and y-coordinates, which respectively 
specify a pixel’s horizontal and vertical location in an image. The origin is 
the pixel at the top-left corner of the image and is specified with the nota- 
tion (0, 0). The first zero represents the x-coordinate, which starts at zero 
at the origin and increases going from left to right. The second zero repre- 
sents the y-coordinate, which starts at zero at the origin and increases going 
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down the image. This bears repeating: 
y-coordinates increase going downward, 
which is the opposite of how you may 
remember y-coordinates being used in 
math class. Figure 17-1 demonstrates how 
this coordinate system works. 

Many of Pillow’s functions and 
methods take a box tuple argument. This 
means Pillow is expecting a tuple of four 
integer coordinates that represent a rect- 
angular region in an image. The four 
integers are, in order, as follows: 


e = Left: The x-coordinate of the leftmost 
edge of the box. 


e Top: The y-coordinate of the top edge 
of the box. 


e Right: The x-coordinate of one pixel 
to the right of the rightmost edge of 
the box. This integer must be greater 
than the left integer. 


e Bottom: The y-coordinate of one pixel 
lower than the bottom edge of the 
box. This integer must be greater 
than the top integer. 


Note that the box includes the left 
and top coordinates and goes up to but 
does not include the right and bottom 
coordinates. For example, the box tuple 
(3, 1, 9, 6) represents all the pixels in 
the black box in Figure 17-2. 
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X increases 


(0,0) 


y increases 





(27,26) 


Figure 17-1: The x- and y-coordinates 
of a 27x26 image of some sort of 
ancient data storage device 


0123456789 


OOANDNAFWNH— CO 


Figure 17-2: The area represented 
by the box tuple (3, 1, 9, 6) 


Now that you know how colors and coordinates work in Pillow, let’s use 
Pillow to manipulate an image. Figure 17-3 is the image that will be used 
for all the interactive shell examples in this chapter. You can download it 


from hitp://nostarch.com/automatestuff/. 


Once you have the image file Zophie.png in your current working direc- 
tory, you’ll be ready to load the image of Zophie into Python, like so: 





>>> from PIL import Image 
>>> catIm = Image.open('zophie.png' ) 








Figure 17-3: My cat Zophie. The camera 
adds 10 pounds (which is a lot for a cat). 


To load the image, you import the Image module from Pillow and call 
Image.open(), passing it the image’s filename. You can then store the loaded 
image in a variable like CatIm. The module name of Pillow is PIL to make it 
backward compatible with an older module called Python Imaging Library, 
which is why you must run from PIL import Image instead of from Pillow import 
Image. Because of the way Pillow’s creators set up the pillow module, you must 
use the from PIL import Image form of import statement, rather than simply 
import PIL. 

If the image file isn’t in the current working directory, change the 
working directory to the folder that contains the image file by calling the 
os.chdir() function. 





>>> import os 
>>> os.chdir('C:\\folder_with_image_ file’ ) 





The Image.open() function returns a value of the Image object data type, 
which is how Pillow represents an image as a Python value. You can load an 
Image object from an image file (of any format) by passing the Image. open() 
function a string of the filename. Any changes you make to the Image 
object can be saved to an image file (also of any format) with the save() 
method. All the rotations, resizing, cropping, drawing, and other image 
manipulations will be done through method calls on this Image object. 

To shorten the examples in this chapter, I'll assume you've imported 
Pillow’s Image module and that you have the Zophie image stored in a variable 
named catIm. Be sure that the zophie.png file is in the current working direc- 
tory so that the Image.open() function can find it. Otherwise, you will also have 
to specify the full absolute path in the string argument to Image. open(). 
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Working with the Image Data Type 
An Image object has several useful attributes that give you basic information 
about the image file it was loaded from: its width and height, the filename, 
and the graphics format (such as JPEG, GIF, or PNG). 

For example, enter the following into the interactive shell: 





>>> from PIL import Image 

>>> catIm = Image.open('zophie.png' ) 
>>> catIm.size 

(816, 1088) 

>>> width, height = catIm.size 
>>> width 

816 

>>> height 

1088 

>>> catIm.filename 
"zophie.png' 

>>> catIm. format 

"PNG' 

>>> catIm.format_description 
‘Portable network graphics’ 
>>> catIm.save('zophie. jpg’ ) 





After making an Image object from Zophie.png and storing the Image 
object in catIm, we can see that the object’s size attribute contains a tuple 
of the image’s width and height in pixels ®. We can assign the values in the 
tuple to width and height variables @ in order to access with width © and 
height @ individually. The filename attribute describes the original file’s 
name. The format and format_description attributes are strings that describe 
the image format of the original file (with format_description being a bit 
more verbose). 

Finally, calling the save() method and passing it 'zophie.jpg' saves a new 
image with the filename zophiejpg to your hard drive ®. Pillow sees that the 
file extension is .jpg and automatically saves the image using the JPEG image 
format. Now you should have two images, zophie.png and zophie.jpg, on your 
hard drive. While these files are based on the same image, they are not iden- 
tical because of their different formats. 

Pillow also provides the Image.new() function, which returns an Image 
object—much like Image.open(), except the image represented by Image.new()’s 
object will be blank. The arguments to Image.new() are as follows: 


e The string 'RGBA', which sets the color mode to RGBA. (There are other 
modes that this book doesn’t go into.) 


e The size, as a two-integer tuple of the new image’s width and height. 


e The background color that the image should start with, as a four- 
integer tuple of an RGBA value. You can use the return value of 
the ImageColor.getcolor() function for this argument. Alternatively, 
Image.new() also supports just passing the string of the standard 
color name. 


For example, enter the following into the interactive shell: 





>>> from PIL import Image 

>>> im = Image.new('RGBA', (100, 200), ‘purple') 
>>> im.save('purpleImage.png' ) 

>>> im2 = Image.new('RGBA', (20, 20)) 

>>> im2.save('transparentImage.png' ) 





Here we create an Image object for an image that’s 100 pixels wide and 
200 pixels tall, with a purple background ®. This image is then saved to 
the file purplelmage.png. We call Image.new() again to create another Image 
object, this time passing (20, 20) for the dimensions and nothing for the 
background color @. Invisible black, (0, 0, 0, 0), is the default color used if 
no color argument is specified, so the second image has a transparent back- 
ground; we save this 20x20 transparent square in ¢ransparentImage.png. 


Cropping Images 
Cropping an image means selecting a rectangular region inside an image 
and removing everything outside the rectangle. The crop() method on 
Image objects takes a box tuple and returns an Image object representing 
the cropped image. The cropping does not happen in place—that is, the 
original Image object is left untouched, and the crop() method returns a 
new Image object. Remeber that a boxed tuple—in this case, the cropped 
section—includes the left column and top row of pixels but only goes up 
to and does not include the right column and bottom row of pixels. 
Enter the following into the interactive shell: 





>>> croppedIm = catIm.crop((335, 345, 565, 560)) 
>>> croppedIm.save('cropped.png' ) 





This makes a new Image object for the cropped image, stores the 
object in croppedIm, and then calls save() on croppedIm to save the cropped 
image in cropped.png. The new file cropped.png will be created from the ori- 
ginal image, like in Figure 17-4. 
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Figure 17-4: The new image will be just the cropped 
section of the original image. 


Copying and Pasting Images onto Other Images 


The copy() method will return a new Image object with the same image 
as the Image object it was called on. This is useful if you need to make 
changes to an image but also want to keep an untouched version of the 
original. For example, enter the following into the interactive shell: 





>>> catIm = Image.open('zophie.png' ) 
>>> catCopyIm = catIm.copy() 





The catIm and catCopyIm variables contain two separate Image objects, 
which both have the same image on them. Now that you have an Image 
object stored in catCopyIm, you can modify catCopyIm as you like and save 
it to anew filename, leaving zophie.png untouched. For example, let’s try 
modifying catCopyIm with the paste() method. 

The paste() method is called on an Image object and pastes another image 
on top of it. Let’s continue the shell example by pasting a smaller image onto 
catCopyIm. 





>>> faceIm = catIm.crop((335, 345, 565, 560)) 
>>> faceIm.size 

(230, 215) 

>>> catCopyIm.paste(faceIm, (0, 0)) 

>>> catCopyIm.paste(faceIm, (400, 500)) 

>>> catCopyIm.save('pasted.png' ) 


First we pass crop() a box tuple for the rectangular area in zophie.png 
that contains Zophie’s face. This creates an Image object representing a 
230x215 crop, which we store in faceIm. Now we can paste faceIm onto 
catCopyIm. The paste() method takes two arguments: a “source” Image 
object and a tuple of the x- and y-coordinates where you want to paste 
the top-left corner of the source Image object onto the main Image object. 
Here we call paste() twice on catCopyIm, passing (0, 0) the first time and 
(400, 500) the second time. This pastes faceIm onto catCopyIm twice: once 
with the top-left corner of faceIm at (0, 0) on catCopyIm, and once with 
the top-left corner of faceIm at (400, 500). Finally, we save the modified 
catCopyIm to pasted.png. The pasted.png image looks like Figure 17-5. 





Figure 17-5: Zophie the cat, with her face 
pasted twice 


Despite their names, the copy() and paste() methods in Pillow do not use your com- 
puter’s clipboard. 


Note that the paste() method modifies its Image object in place; it does 
not return an Image object with the pasted image. If you want to call paste() 
but also keep an untouched version of the original image around, you'll 
need to first copy the image and then call paste() on that copy. 

Say you want to tile Zophie’s head across the entire image, as in 
Figure 17-6. You can achieve this effect with just a couple for loops. 
Continue the interactive shell example by entering the following: 





>>> catImWidth, catImHeight = catIm.size 
>>> faceImWidth, faceImHeight = faceIm.size 


@ >>> catCopyTwo = catIm.copy() 


Manipulating Images 395 


@ >>> for left in range(0, catImWidth, faceImWidth): 
© for top in range(0, catImHeight, faceImHeight): 
print(left, top) 
catCopyTwo.paste(faceIm, (left, top)) 
00 
0 215 
0 430 
0 645 
0 860 
0 1075 
230 0 
230 215 
--snip-- 
690 860 
690 1075 
>>> catCopyTwo.save('tiled.png') 





Here we store the width of height of catIm in catImWidth and 
catImHeight. At ® we make a copy of catIm and store it in catCopyTwo. Now 
that we have a copy that we can paste onto, we start looping to paste faceIm 
onto catCopyTwo. The outer for loop’s left variable starts at 0 and increases by 
faceImWidth(230) @. The inner for loop’s top variable start at 0 and increases 
by faceImHeight(215) ©. These nested for loops produce values for left and 
top to paste a grid of faceIm images over the catCopyTwo Image object, as in 
Figure 17-6. To see our nested loops working, we print left and top. After 
the pasting is complete, we save the modified catCopyTwo to tiled.png. 





Figure 17-6: Nested for loops used 
with paste() to duplicate the cat's face 
(a dupli-cat, if you will). 
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PASTING TRANSPARENT PIXELS 


Normally transparent pixels are pasted as white pixels. If the image you want 
to paste has transparent pixels, pass the Image object as the third argument 

so that a solid rectangle isn’t pasted. This third argument is the “mask” Image 
object. A mask is an Image object where the alpha value is significant, but the 
red, green, and blue values are ignored. The mask tells the paste() function 
which pixels it should copy and which it should leave transparent. Advanced 


usage of masks is beyond this book, but if you want to paste an image that has 


transparent pixels, pass the Image object again as the third argument. 





Resizing an Image 


The resize() method is called on an Image object and returns a new Image 
object of the specified width and height. It accepts a two-integer tuple argu- 
ment, representing the new width and height of the returned image. Enter 
the following into the interactive shell: 





>>> width, height = catIm.size 

>>> quartersizedIm = catIm.resize((int(width / 2), int(height / 2))) 
>>> quartersizedIm.save('quartersized.png' ) 

>>> svelteIm = catIm.resize((width, height + 300)) 

>>> svelteIm.save('svelte. png’) 


Here we assign the two values in the catIm.size tuple to the variables 
width and height ®. Using width and height instead of catIm.size[o] and 
catIm.size[1] makes the rest of the code more readable. 

The first resize() call passes int(width / 2) for the new width and 
int(height / 2) for the new height 8, so the Image object returned from 
resize() will be half the length and width of the original image, or one- 
quarter of the original image size overall. The resize() method accepts 
only integers in its tuple argument, which is why you needed to wrap both 
divisions by 2 in an int() call. 

This resizing keeps the same proportions for the width and height. But 
the new width and height passed to resize() do not have to be proportional 
to the original image. The svelteIm variable contains an Image object that 
has the original width but a height that is 300 pixels taller ®, giving Zophie 
a more slender look. 

Note that the resize() method does not edit the Image object in place 
but instead returns a new Image object. 
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Rotating and Flipping Images 


Images can be rotated with the rotate() method, which returns a new Image 
object of the rotated image and leaves the original Image object unchanged. 
The argument to rotate() is a single integer or float representing the num- 
ber of degrees to rotate the image counterclockwise. Enter the following 
into the interactive shell: 





>>> catIm.rotate(90).save('rotated90. png’ ) 
>>> catIm.rotate(180).save('rotated180.png' ) 
>>> catIm.rotate(270).save('rotated270.png' ) 





Note how you can chain method calls by calling save() directly on the 
Image object returned from rotate(). The first rotate() and save() call makes 
a new Image object representing the image rotated counterclockwise by 
90 degrees and saves the rotated image to rotated90.png. The second and 
third calls do the same, but with 180 degress and 270 degress. The results 
look like Figure 17-7. 





Figure 17-7: The original image (left) and the image rotated counterclockwise by 90, 180, 
and 270 degrees 


Notice that the width and height of the image change when the image 
is rotated 90 or 270 degrees. If you rotate an image by some other amount, 
the original dimensions of the image are maintained. On Windows, a 
black background is used to fill in any gaps made by the rotation, like in 
Figure 17-8. On OS X, transparent pixels are used for the gaps instead. 

The rotate() method has an optional expand keyword argument that can 
be set to True to enlarge the dimensions of the image to fit the entire rotated 
new image. For example, enter the following into the interactive shell: 





>>> catIm.rotate(6).save('rotated6.png' ) 
>>> catIm.rotate(6, expand=True).save('rotated6_expanded.png' ) 





The first call rotates the image 6 degrees and saves it to rotate6.png (see 
the image on the left of Figure 17-8). The second call rotates the image 6 
degrees with expand set to True and saves it to rotate6_expanded.png (see the 
image on the right of Figure 17-8). 





Figure 17-8: The image rotated 6 degrees normally (left) and with expand=True (right) 


You can also get a “mirror flip” of an image with the transpose() method. 
You must pass either Image.FLIP_LEFT_RIGHT or Image.FLIP_TOP_BOTTOM to the 
transpose() method. Enter the following into the interactive shell: 





>>> catIm.transpose(Image.FLIP_LEFT_RIGHT).save('horizontal_flip.png' ) 
>>> catIm.transpose(Image.FLIP_TOP_BOTTOM).save('vertical_flip.png' ) 





Like rotate(), transpose() creates a new Image object. Here was pass 
Image.FLIP_LEFT_RIGHT to flip the image horizontally and then save the result 
to horizontal_flip.png. To flip the image vertically, we pass Image.FLIP_TOP_ 
BOTTOM and save to vertical_flip.png. The results look like Figure 17-9. 


4 p 
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Figure 17-9: The original image (left), horizontal flip (center), and vertical flip (right) 
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Changing Individual Pixels 


The color of an individual pixel can be retrieved or set with the getpixel() 
and putpixel() methods. These methods both take a tuple representing the 
x- and y-coordinates of the pixel. The putpixel() method also takes an addi- 
tional tuple argument for the color of the pixel. This color argument is a 
four-integer RGBA tuple or a three-integer RGB tuple. Enter the following 
into the interactive shell: 





>>> im = Image.new('RGBA', (100, 100)) 
>>> im.getpixel((0, 0)) 
(0, 0, 0, 0) 
>>> for x in range(100): 
for y in range(50): 
im.putpixel((x, y), (210, 210, 210)) 


>>> from PIL import ImageColor 
>>> for x in range(100): 

for y in range(50, 100): 

im.putpixel((x, y), ImageColor.getcolor('darkgray', 'RGBA')) 

>>> im.getpixel((0, 0)) 
(210, 210, 210, 255) 
>>> im.getpixel((0, 50)) 
(169, 169, 169, 255) 
>>> im.save('putPixel.png' ) 





At © we make a new image that is a 100x100 transparent square. 
Calling getpixel() on some coordinates in this image returns (0, 0, 0, 0) 
because the image is transparent ®. To color pixels in this image, we can 
use nested for loops to go through all the pixels in the top half of the 
image ® and color each pixel using putpixel() @. Here we pass putpixel() 
the RGB tuple (210, 210, 210), a light gray. 

Say we want to color the bottom half of the image dark gray but don’t 
know the RGB tuple for dark gray. The putpixel() method doesn’t accept a 
standard color name like 'darkgray', so you have to use ImageColor.getcolor() 
to get a color tuple from 'darkgray'. Loop through 
the pixels in the bottom half of the image ® and pass 
putpixel() the return value of ImageColor.getcolor() @, 
and you should now have an image that is light gray 
in its top half and dark gray in the bottom half, as 
shown in Figure 17-10. You can call getpixel() on some 
coordinates to confirm that the color at any given 
pixel is what you expect. Finally, save the image to 
putPixel.png: : . r Figure 17-10: The 

Of course, drawing one pixel at a time onto 
an image isn’t very convenient. If you need to draw 
shapes, use the ImageDraw functions explained later 
in this chapter. 


putPixel.png image 


Project: Adding a Logo 


Say you have the boring job of resizing thousands 
of images and adding a small logo watermark to 
the corner of each. Doing this with a basic graph- 
ics program such as Paintbrush or Paint would 
take forever. A fancier graphics application such 
as Photoshop can do batch processing, but that 
software costs hundreds of dollars. Let’s write a 
script to do it instead. 


add to the bottom-right corner of each image: a 





Say that Figure 17-11 is the logo you want to 


black cat icon with a white border, with the rest Figure 17-11: The logo to be 


of the image transparent. 
Ata high level, here’s what the program 


added to the image. 


should do: 


Load the logo image. 
Loop over all .png and.jpg files in the working directory. 
Check whether the image is wider or taller than 300 pixels. 


If so, reduce the width or height (whichever is larger) to 300 pixels and 
scale down the other dimension proportionally. 


Paste the logo image into the corner. 


Save the altered images to another folder. 
This means the code will need to do the following: 


Open the catlogo.png file as an Image object. 

Loop over the strings returned from os.listdir('.'). 

Get the width and height of the image from the size attribute. 
Calculate the new width and height of the resized image. 

Call the resize() method to resize the image. 

Call the paste() method to paste the logo. 


Call the save() method to save the changes, using the original filename. 


Step 1: Open the Logo Image 


For this project, open a new file editor window, enter the following code, 
and save it as resizeAndAddLogo.py: 





#! python3 
# resizeAndAddLogo.py - Resizes all images in current working directory to fit 
# in a 300x300 square, and adds catlogo.png to the lower-right corner. 
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import os 
from PIL import Image 


SQUARE_FIT_SIZE = 300 
LOGO_FILENAME = 'catlogo.png' 


logoIm = Image.open(LOGO_FILENAME) 
logoWidth, logoHeight = logoIm.size 


# TODO: Loop over all files in the working directory. 

# TODO: Check if image needs to be resized. 

# TODO: Calculate the new width and height to resize to. 
# TODO: Resize the image. 

# TODO: Add the logo. 


# TODO: Save changes. 





By setting up the SQUARE_FIT_SIZE ® and LOGO_FILENAME @ constants at the 
start of the program, we’ve made it easy to change the program later. Say 
the logo that you're adding isn’t the cat icon, or say you're reducing the out- 
put images’ largest dimension to something other than 300 pixels. With these 
constants at the start of the program, you can just open the code, change 
those values once, and you're done. (Or you can make it so that the values 
for these constants are taken from the command line arguments.) Without 
these constants, you’d instead have to search the code for all instances of 
300 and ‘catlogo.png' and replace them with the values for your new project. 
In short, using constants makes your program more generalized. 

The logo Image object is returned from Image.open() ®. For readability, 
logoWidth and logoHeight are assigned to the values from logoIm.size @. 

The rest of the program is a skeleton of TODO comments for now. 


Step 2: Loop Over All Files and Open Images 


Now you need to find every .png file and .jpg file in the current working 
directory. Note that you don’t want to add the logo image to the logo image 
itself, so the program should skip any image with a filename that’s the same 
as LOGO_FILENAME. Add the following to your code: 





#! python3 
# resizeAndAddLogo.py - Resizes all images in current working directory to fit 
# in a 300x300 square, and adds catlogo.png to the lower-right corner. 


import os 
from PIL import Image 


--snip-- 
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os.makedirs('withLogo', exist_ok=True) 
# Loop over all files in the working directory. 
for filename in os.listdir('.'): 
if not (filename.endswith('.png') or filename.endswith('.jpg')) \ 
or filename == LOGO_FILENAME: 
continue # skip non-image files and the logo file itself 


im = Image.open(filename) 
width, height = im.size 


--snip-- 





First, the os.makedirs() call creates a withLogo folder to store the fin- 
ished images with logos, instead of overwriting the original image files. 
The exist_ok=True keyword argument will keep os.makedirs() from raising 
an exception if withLogo already exists. While looping through all the files 
in the working directory with os.listdir('.') @, the long if statement @ 
checks whether each filename doesn’t end with .png or .jpg. If so—or if the 
file is the logo image itself—then the loop should skip it and use continue © 
to go to the next file. If filename does end with '.png' or '.jpg' (and isn’t the 
logo file), you can open it as an Image object @ and set width and height. 


Step 3: Resize the Images 


The program should resize the image only if the width or height is larger 
than SQUARE_FIT_SIZE (300 pixels, in this case), so put all of the resizing code 
inside an if statement that checks the width and height variables. Add the 
following code to your program: 





#! python3 
# resizeAndAddLogo.py - Resizes all images in current working directory to fit 
# in a 300x300 square, and adds catlogo.png to the lower-right corner. 


import os 
from PIL import Image 


--snip-- 


# Check if image needs to be resized. 

if width > SQUARE_FIT_SIZE and height > SQUARE_FIT_SIZE: 
# Calculate the new width and height to resize to. 
if width > height: 


height = int((SQUARE FIT SIZE / width) * height) 
width = SQUARE_FIT_SIZE 

else: 
width = int((SQUARE_FIT SIZE / height) * width) 
height = SQUARE _FIT SIZE 

# Resize the image. 

print('Resizing %s...' % (filename) ) 

© im = im.resize( (width, height)) 


--snip-- 
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If the image does need to be resized, you need to find out whether it is 
a wide or tall image. If width is greater than height, then the height should 
be reduced by the same proportion that the width would be reduced ®. 
This proportion is the SQUARE_FIT_SIZE value divided by the current width. 
The new height value is this proportion multiplied by the current height 
value. Since the division operator returns a float value and resize() requires 
the dimensions to be integers, remember to convert the result to an integer 
with the int() function. Finally, the new width value will simply be set to 
SQUARE_FIT_SIZE 

If the height is greater than or equal to the width (both cases are handled 
in the else clause), then the same calculation is done, except with the height 
and width variables swapped @. 

Once width and height contain the new image dimensions, pass them to 
the resize() method and store the returned Image object in im ®. 


Step 4: Add the Logo and Save the Changes 


Whether or not the image was resized, the logo should still be pasted to the 
bottom-right corner. Where exactly the logo should be pasted depends on 
both the size of the image and the size of the logo. Figure 17-12 shows how 
to calculate the pasting position. The left coordinate for where to paste the 
logo will be the image width minus the logo width; the top coordinate for 
where to paste the logo will be the image height minus the logo height. 


Image width 


Logo width 


Image height 
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Figure 17-12: The left and top coordinates for 
placing the logo in the bottom-right corner 
should be the image width/height minus the 
logo width/height. 


After your code pastes the logo into the image, it should save the modi- 
fied Image object. Add the following to your program: 





#! python3 
# resizeAndAddLogo.py - Resizes all images in current working directory to fit 
# in a 300x300 square, and adds catlogo.png to the lower-right corner. 


import os 
from PIL import Image 


eo 


--snip-- 


# Check if image needs to be resized. 
--snip-- 


# Add the logo. 
print('Adding logo to %s...' % (filename) ) 
im.paste(logoIm, (width - logoWidth, height - logoHeight), logoIm) 


# Save changes. 
im.save(os.path.join('withLogo', filename) ) 





The new code prints a message telling the user that the logo is being 
added @, pastes logoIm onto im at the calculated coordinates @, and saves 
the changes to a filename in the withLogo directory ®. When you run this 
program with the zophie.png file as the only image in the working directory, 
the output will look like this: 





Resizing zophie.png... 
Adding logo to zophie.png... 





The image zophie.png will be changed to a 225x300-pixel image that 
looks like Figure 17-13. Remember that the paste() method will not paste 
the transparency pixels if you do not pass the logoIm for the third argument 
as well. This program can automatically resize and “logo-ify” hundreds of 
images in just a couple minutes. 


. 7 . 





Figure 17-13: The image zophie.png resized and the logo added (left). If you forget the 
third argument, the transparent pixels in the logo will be copied as solid white pixels (right). 
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Ideas for Similar Programs 


Being able to composite images or modify image sizes in a batch can be 
useful in many applications. You could write similar programs to do the 
following: 


e Add text or a website URL to images. 
e Add timestamps to images. 
e Copy or move images into different folders based on their sizes. 


e Adda mostly transparent watermark to an image to prevent others 
from copying it. 


Drawing on Images 


Chapter 17 


If you need to draw lines, rectangles, circles, or other simple shapes on 
an image, use Pillow’s ImageDraw module. Enter the following into the inter- 
active shell: 





>>> from PIL import Image, ImageDraw 
>>> im = Image.new('RGBA', (200, 200), ‘white') 
>>> draw = ImageDraw.Draw(im) 





First, we import Image and ImageDraw. Then we create a new image, in this 
case, a 200x200 white image, and store the Image object in im. We pass the 
Image object to the ImageDraw.Draw() function to receive an ImageDraw object. 
This object has several methods for drawing shapes and text onto an Image 
object. Store the ImageDraw object in a variable like draw so you can use it eas- 
ily in the following example. 


Drawing Shapes 


The following ImageDraw methods draw various kinds of shapes on the 
image. The fill and outline parameters for these methods are optional and 
will default to white if left unspecified. 


Points 


The point(xy, fill) method draws individual pixels. The xy argument 
represents a list of the points you want to draw. The list can be a list of 

x- and y-coordinate tuples, such as [(x, y), (x, y), .-.], ora list of x- and 
y-coordinates without tuples, such as [x1, y1, x2, y2, ...]. The fill argu- 
ment is the color of the points and is either an RGBA tuple or a string of 
a color name, such as 'red'. The fill argument is optional. 


Lines 


The line(xy, fill, width) method draws a line or series of lines. xy is either 
a list of tuples, such as [(x, y), (x, y), ...], ora list of integers, such as 
[x1, y1, x2, y2, ...]. Each point is one of the connecting points on the 
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lines you’re drawing. The optional fill argument is the color of the lines, 
as an RGBA tuple or color name. The optional width argument is the width 
of the lines and defaults to 1 if left unspecified. 


Rectangles 


The rectangle(xy, fill, outline) method draws a rectangle. The xy argu- 
ment is a box tuple of the form (left, top, right, bottom). The left and top 
values specify the x- and y-coordinates of the upper-left corner of the rect- 
angle, while right and bottom specify the lower-right corner. The optional 
fill argument is the color that will fill the inside of the rectangle. The 
optional outline argument is the color of the rectangle’s outline. 


Ellipses 


The ellipse(xy, fill, outline) method draws an ellipse. If the width and 
height of the ellipse are identical, this method will draw a circle. The xy 
argument is a box tuple (left, top, right, bottom) that represents a box that 
precisely contains the ellipse. The optional fill argument is the color of the 
inside of the ellipse, and the optional outline argument is the color of the 
ellipse’s outline. 


Polygons 


The polygon(xy, fill, outline) method draws an arbitrary polygon. The xy 
argument is a list of tuples, such as [(x, y), (x, y), ...], or integers, such 
as [x1, y1, x2, y2, ...], representing the connecting points of the polygon’s 
sides. The last pair of coordinates will be automatically connected to the 
first pair. The optional fill argument is the color of the inside of the poly- 
gon, and the optional outline argument is the color of the polygon’s outline. 


Drawing Example 


Enter the following into the interactive shell: 





>>> from PIL import Image, ImageDraw 
>>> im = Image.new('RGBA', (200, 200), ‘white') 
>>> draw = ImageDraw.Draw(im) 
>>> draw.line([(0, 0), (199, 0), (199, 199), (0, 199), (0, 0)], fill='black') 
>>> draw.rectangle((20, 30, 60, 60), fill='blue') 
>>> draw.ellipse((120, 30, 160, 60), fill='red') 
>>> draw.polygon(((57, 87), (79, 62), (94, 85), (120, 90), (103, 113)), 
fill='brown' ) 
>>> for i in range(100, 200, 10): 
draw.line([(i, 0), (200, i - 100)], fill='green') 


>>> im.save('drawing.png' ) 





After making an Image object for a 200x200 white image, passing it to 
ImageDraw.Draw() to get an ImageDraw object, and storing the ImageDraw object 
in draw, you can call drawing methods on draw. Here we make a thin, black 
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outline at the edges of the image 9, a blue rectangle with its top-left corner 
at (20, 30) and bottom-right corner at (60, 60) , a red ellipse defined by a 
box from (120, 30) to (160, 60) ©, a brown polygon with five points @, and 
a pattern of green lines drawn with a for loop ©. The resulting drawing.png 
file will look like Figure 17-14. 





Figure 17-14: The resulting drawing.png 
image 


There are several other shape-drawing methods for ImageDraw objects. 
The full documentation is available at hitp://pillow.readthedocs.org/en/latest/ 
reference/ImageDraw.html. 


Drawing Text 


The ImageDraw object also has a text() method for drawing text onto an 
image. The text() method takes four arguments: xy, text, fill, and font. 


e The xy argument is a two-integer tuple specifying the upper-left corner 
of the text box. 


e The text argument is the string of text you want to write. 
e The optional fill argument is the color of the text. 


e The optional font argument is an ImageFont object, used to set the type- 
face and size of the text. This is described in more detail in the next 
section. 


Since it’s often hard to know in advance what size a block of text will 
be in a given font, the ImageDraw module also offers a textsize() method. 
Its first argument is the string of text you want to measure, and its second 
argument is an optional ImageFont object. The textsize() method will then 
return a two-integer tuple of the width and height that the text in the given 
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font would be if it were written onto the image. You can use this width and 
height to help you calculate exactly where you want to put the text on your 
image. 

The first three arguments for text() are straightforward. Before we use 
text() to draw text onto an image, let’s look at the optional fourth argument, 
the ImageFont object. 

Both text() and textsize() take an optional ImageFont object as their 
final arguments. To create one of these objects, first run the following: 





>>> from PIL import ImageFont 





Now that you’ve imported Pillow’s ImageFont module, you can call the 
ImageFont.truetype() function, which takes two arguments. The first argu- 
ment is a string for the font’s TrueType file—this is the actual font file that 
lives on your hard drive. A TrueType file has the .tt/file extension and can 
usually be found in the following folders: 


e On Windows: C:\Windows\Fonts 
e OnOS X: /Library/Fonts and /System/Library/Fonts 
e On Linux: /usr/share/fonts/truetype 


You don’t actually need to enter these paths as part of the TrueType 
file string because Python knows to automatically search for fonts in these 
directories. But Python will display an error if it is unable to find the font 
you specified. 

The second argument to ImageFont.truetype() is an integer for the font 
size in points (rather than, say, pixels). Keep in mind that Pillow creates 
PNG images that are 72 pixels per inch by default, and a point is 1/72 of 
an inch. 

Enter the following into the interactive shell, replacing FONT_FOLDER with 
the actual folder name your operating system uses: 


>>> from PIL import Image, ImageDraw, ImageFont 

>>> import os 

>>> im = Image.new('RGBA', (200, 200), ‘white') 

>>> draw = ImageDraw.Draw(im) 

>>> draw.text((20, 150), ‘Hello’, fill='purple') 

>>> fontsFolder = 'FONT_FOLDER' # e.g. ‘/Library/Fonts’ 

>>> arialFont = ImageFont.truetype(os.path.join(fontsFolder, ‘arial.ttf'), 32) 
>>> draw.text((100, 150), ‘Howdy’, fill='gray', font=arialFont) 

>>> im.save('text.png') 





After importing Image, ImageDraw, ImageFont, and os, we make an Image 
object for a new 200x200 white image @ and make an ImageDraw object from 
the Image object @. We use text() to draw Hello at (20, 150) in purple ®. We 
didn’t pass the optional fourth argument in this text() call, so the typeface 
and size of this text aren’t customized. 
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To set a typeface and size, we first 
store the folder name (like /Library/ 
Fonts) in fontsFolder. Then we call 
ImageFont.truetype(), passing it the .tif 
file for the font we want, followed by 
an integer font size @. Store the Font 
object you get from ImageFont.truetype() 
in avariable like arialFont, and then 
pass the variable to text() in the final ae 
keyword argument. The text() call at © H owd y 
draws Howdy at (100, 150) in gray in 
32-point Arial. 
The resulting text.png file will look Figure 17-15: The resulting text.png 
like Figure 17-15. image 





Summary 


Images consist of a collection of pixels, and each pixel has an RGBA value 
for its color and its addressable by x- and y-coordinates. Two common image 
formats are JPEG and PNG. The pillow module can handle both of these 
image formats and others. 

When an image is loaded into an Image object, its width and height 
dimensions are stored as a two-integer tuple in the size attribute. Objects of the 
Image data type also have methods for common image manipulations: crop(), 
copy(), paste(), resize(), rotate(), and transpose(). To save the Image object to 
an image file, call the save() method. 

If you want your program to draw shapes onto an image, use ImageDraw 
methods to draw points, lines, rectangles, ellipses, and polygons. The mod- 
ule also provides methods for drawing text in a typeface and font size of 
your choosing. 

Although advanced (and expensive) applications such as Photoshop 
provide automatic batch processing features, you can use Python scripts to 
do many of the same modifications for free. In the previous chapters, you 
wrote Python programs to deal with plaintext files, spreadsheets, PDFs, and 
other formats. With the pillow module, you’ve extended your programming 
powers to processing images as well! 


Practice Questions 
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1. What is an RGBA value? 

2. How can you get the RGBA value of 'CornflowerBlue' from the Pillow 
module? 

3. What is a box tuple? 


What function returns an Image object for, say, an image file named 
zophie.png? 


Practice 


5. How can you find out the width and height of an Image objects image? 


6. What method would you call to get Image object for a 100x100 image, 
excluding the lower left quarter of it? 


7. After making changes to an Image object, how could you save it as an 
image file? 
8. What module contains Pillow’s shape-drawing code? 


Image objects do not have drawing methods. What kind of object does? 
How do you get this kind of object? 


Projects 


For practice, write programs that do the following. 


Extending and Fixing the Chapter Project Programs 


The resizeAndAddLogo.py program in this chapter works with PNG and JPEG 
files, but Pillow supports many more formats than just these two. Extend 
resizeAndAddLogo.py to process GIF 
and BMP images as well. 

Another small issue is that the 
program modifies PNG and JPEG 
files only if their file extensions are 
set in lowercase. For example, it will 
process zophie.png but not zophie.PNG. 
Change the code so that the file 
extension check is case insensitive. 

Finally, the logo added to the 
bottom-right corner is meant to be 
just a small mark, but if the image is 
about the same size as the logo itself, 
the result will look like Figure 17-16. 
Modify resizeAndAddLogo.py so that 
the image must be at least twice the 
width and height of the logo image 
before the logo is pasted. Otherwise, 
it should skip adding the logo. 





Figure 17-16: When the image isn’t much 
larger than the logo, the results look ugly. 


Identifying Photo Folders on the Hard Drive 


I have a bad habit of transferring files from my digital camera to temporary 
folders somewhere on the hard drive and then forgetting about these fold- 
ers. It would be nice to write a program that could scan the entire hard 
drive and find these leftover “photo folders.” 

Write a program that goes through every folder on your hard drive and 
finds potential photo folders. Of course, first you’ll have to define what you 
consider a “photo folder” to be; let’s say that it’s any folder where more than 
half of the files are photos. And how do you define what files are photos? 
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First, a photo file must have the file extension .png or .jpg. Also, photos 
are large images; a photo file’s width and height must both be larger than 
500 pixels. This is a safe bet, since most digital camera photos are several 
thousand pixels in width and height. 

As a hint, here’s a rough skeleton of what this program might look like: 


#! python3 
# Import modules and write comments to describe this program. 


for foldername, subfolders, filenames in os.walk('C:\\'): 
numPhotoFiles = 0 
numNonPhotoFiles = 0 
for filename in filenames: 
# Check if file extension isn't .png or .jpg. 
if TODO: 
numNonPhotoFiles += 1 
continue # skip to next filename 


# Open image file using Pillow. 


# Check if width & height are larger than 500. 

if TODO: 
# Image is large enough to be considered a photo. 
numPhotoFiles += 1 

else: 
# Image is too small to be a photo. 
numNonPhotoFiles += 1 


# If more than half of files were photos, 
# print the absolute path of the folder. 
if TODO: 

print (TODO) 





When the program runs, it should print the absolute path of any photo 
folders to the screen. 


Custom Seating Cards 


Chapter 13 included a practice project to create custom invitations from 

a list of guests in a plaintext file. As an additional project, use the pillow 
module to create images for custom seating cards for your guests. For 
each of the guests listed in the guests.txt file from the resources at hitp:// 
nostarch.com/automatestuff/, generate an image file with the guest name and 
some flowery decoration. A public domain flower image is available in the 
resources at hitp://nostarch.com/automatestuff/. 

To ensure that each seating card is the same size, add a black rectangle 
on the edges of the invitation image so that when the image is printed out, 
there will be a guideline for cutting. The PNG files that Pillow produces are 
set to 72 pixels per inch, so a 4x5-inch card would require a 288x360-pixel 
image. 





CONTROLLING THE 
KEYBOARD AND MOUSE 
WITH GUI AUTOMATION 


Knowing various Python modules for edit- 
ing spreadsheets, downloading files, and 
launching programs is useful, but some- 
times there just aren’t any modules for the 
applications you need to work with. The ultimate 
tools for automating tasks on your computer are pro- 
grams you write that directly control the keyboard 


and mouse. These programs can control other applications by sending 
them virtual keystrokes and mouse clicks, just as if you were sitting at your 
computer and interacting with the applications yourself. This technique 
is known as graphical user interface automation, or GUI automation for short. 
With GUI automation, your programs can do anything that a human user 
sitting at the computer can do, except spill coffee on the keyboard. 

Think of GUI automation as programming a robotic arm. You can 
program the robotic arm to type at your keyboard and move your mouse 
for you. This technique is particularly useful for tasks that involve a lot of 
mindless clicking or filling out of forms. 
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The pyautogui module has functions for simulating mouse movements, 
button clicks, and scrolling the mouse wheel. This chapter covers only a 
subset of PyAutoGUI’s features; you can find the full documentation at 
hitp://pyautogut.readthedocs.org/. 


Installing the pyautogui Module 


The pyautogui module can send virtual keypresses and mouse clicks to 
Windows, OS X, and Linux. Depending on which operating system you're 
using, you may have to install some other modules (called dependencies) 
before you can install PyAutoGUI. 


e On Windows, there are no other modules to install. 


e On OSX, run sudo pip3 install pyobjc-framework-Quartz, sudo pip3 
install pyobjc-core, and then sudo pip3 install pyobjc. 


e On Linux, run sudo pip3 install python3-xlib, sudo apt-get install scrot, 
sudo apt-get install python3-tk, and sudo apt-get install python3-dev. 
(Scrot is a screenshot program that PyAutoGUI uses.) 


After these dependencies are installed, run pip install pyautogui (or 
pip3 on OS X and Linux) to install PyAutoGUI. 

Appendix A has complete information on installing third-party modules. 
To test whether PyAutoGUI has been installed correctly, run import pyautogui 
from the interactive shell and check for any error messages. 


Staying on Track 
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Before you jump in to a GUI automation, you should know how to escape 
problems that may arise. Python can move your mouse and type keystrokes 
at an incredible speed. In fact, it might be too fast for other programs to 
keep up with. Also, if something goes wrong but your program keeps mov- 
ing the mouse around, it will be hard to tell what exactly the program is 
doing or how to recover from the problem. Like the enchanted brooms from 
Disney’s The Sorcerer’s Apprentice, which kept filling—and then overfilling— 
Mickey’s tub with water, your program could get out of control even though 
it’s following your instructions perfectly. Stopping the program can be diffi- 
cult if the mouse is moving around on its own, preventing you from clicking 
the IDLE window to close it. Fortunately, there are several ways to prevent 
or recover from GUI automation problems. 


Shutting Down Everything by Logging Out 


Perhaps the simplest way to stop an out-of-control GUI automation program 
is to log out, which will shut down all running programs. On Windows and 
Linux, the logout hotkey is CTRL-ALT-DEL. On OS X, it is #-SHIFT-OPTION-Q. 
By logging out, you’ll lose any unsaved work, but at least you won’t have to 
wait for a full reboot of the computer. 


Pauses and Fail-Safes 


You can tell your script to wait after every function call, giving you a short 
window to take control of the mouse and keyboard if something goes wrong. 
To do this, set the pyautogui.PAUSE variable to the number of seconds you 
want it to pause. For example, after setting pyautogui.PAUSE = 1.5, every 
PyAutoGUI function call will wait one and a half seconds after performing 
its action. Non-PyAutoGUI instructions will not have this pause. 
PyAutoGUI also has a fail-safe feature. Moving the mouse cursor to the 
upper-left corner of the screen will cause PyAutoGUI to raise the pyautogui 
-FailsafeException exception. Your program can either handle this excep- 
tion with try and except statements or let the exception crash your program. 
Either way, the fail-safe feature will stop the program if you quickly move 
the mouse as far up and left as you can. You can disable this feature by set- 
ting pyautogui.FAILSAFE = False. Enter the following into the interactive shell: 





>>> import pyautogui 
>>> pyautogui.PAUSE = 1 
>>> pyautogui.FAILSAFE = True 





Here we import pyautogui and set pyautogui.PAUSE to 1 for a one-second 
pause after each function call. We set pyautogui.FAILSAFE to True to enable 
the fail-safe feature. 


Controlling Mouse Movement 


In this section, you'll learn how to move the mouse and track its position 
on the screen using PyAutoGUI, but first you need to understand how 
PyAutoGUI works with coordinates. 


The mouse functions Panaree 
of PyAutoGUI use x- and ————— ee o 
y-coordinates. Figure 18-1 





shows the coordinate system (191 9,0)? 
for the computer screen; it’s 
similar to the coordinate 
system used for images, dis- 
cussed in Chapter 17. The 
origin, where xand yare 
both zero, is at the upper- 
left corner of the screen. 
The x-coordinates increase 
going to the right, and the 
y-coordinates increase going 
down. All coordinates are 
positive integers; there are 
no negative coordinates. 


y increases 


ROAA (1919,1079) e 


Figure 18-1: The coordinates of a computer screen 
with 1920x1080 resolution 
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Your resolution is how many pixels wide and tall your screen is. If your 
screen’s resolution is set to 1920x1080, then the coordinate for the upper- 
left corner will be (0, 0), and the coordinate for the bottom-right corner 
will be (1919, 1079). 

The pyautogui.size() function returns a two-integer tuple of the screen’s 
width and height in pixels. Enter the following into the interactive shell: 


>>> import pyautogui 

>>> pyautogui.size() 

(1920, 1080) 

>>> width, height = pyautogui.size() 





pyautogui.size() returns (1920, 1080) on a computer with a 1920x1080 
resolution; depending on your screen’s resolution, your return value may be 
different. You can store the width and height from pyautogui.size() in vari- 
ables like width and height for better readability in your programs. 


Moving the Mouse 


Now that you understand screen coordinates, let’s move the mouse. The 
pyautogui.moveTo() function will instantly move the mouse cursor to a specified 
position on the screen. Integer values for the x- and y-coordinates make up 
the function’s first and second arguments, respectively. An optional duration 
integer or float keyword argument specifies the number of seconds it should 
take to move the mouse to the destination. If you leave it out, the default is 
o for instantaneous movement. (All of the duration keyword arguments in 
PyAutoGUI functions are optional.) Enter the following into the interactive 
shell: 





>>> import pyautogui 

>>> for i in range(10): 
pyautogui.moveTo(100, 100, duration=0.25) 
pyautogui.moveTo(200, 100, duration=0.25) 
pyautogui.moveTo(200, 200, duration=0.25) 
pyautogui.moveTo(100, 200, duration=0.25) 


This example moves the mouse cursor clockwise in a square pattern 
among the four coordinates provided a total of ten times. Each movement 
takes a quarter of a second, as specified by the duration=0.25 keyword argu- 
ment. If you hadn't passed a third argument to any of the pyautogui.moveTo() 
calls, the mouse cursor would have instantly teleported from point to point. 

The pyautogui.moveRel() function moves the mouse cursor relative to 
its current position. The following example moves the mouse in the same 
square pattern, except it begins the square from wherever the mouse hap- 
pens to be on the screen when the code starts running: 





>>> import pyautogui 

>>> for i in range(10): 
pyautogui.moveRel(100, 0, duration=0.25) 
pyautogui.moveRel(0, 100, duration=0.25) 


pyautogui.moveRel(-100, 0, duration=0.25) 
pyautogui.moveRel(0, -100, duration=0.25) 





pyautogui.moveRel() also takes three arguments: how many pixels to 
move horizontally to the right, how many pixels to move vertically down- 
ward, and (optionally) how long it should take to complete the movement. 
A negative integer for the first or second argument will cause the mouse to 
move left or upward, respectively. 


Getting the Mouse Position 


You can determine the mouse’s current position by calling the pyautogui 
-position() function, which will return a tuple of the mouse cursor’s xand y 
positions at the time of the function call. Enter the following into the inter- 
active shell, moving the mouse around after each call: 





>>> pyautogui.position() 
(311, 622) 
>>> pyautogui.position() 
(377, 481) 
>>> pyautogui.position() 
(1536, 637) 





Of course, your return values will vary depending on where your mouse 
cursor Is. 


Project: “Where Is the Mouse Right Now?” 


Being able to determine the mouse position is an important part of setting 
up your GUI automation scripts. But it’s almost impossible to figure out the 
exact coordinates of a pixel just by looking at the screen. It would be handy 
to have a program that constantly displays the x- and y-coordinates of the 
mouse cursor as you move it around. 

Ata high level, here’s what your program should do: 


e Display the current x- and y-coordinates of the mouse cursor. 


e Update these coordinates as the mouse moves around the screen. 
This means your code will need to do the following: 


e Call the position() function to fetch the current coordinates. 


e Erase the previously printed coordinates by printing \b backspace char- 
acters to the screen. 


e Handle the KeyboardInterrupt exception so the user can press CTRL-C to 
quit. 


Open a new file editor window and save it as mouseNow.py. 
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Step 1: Import the Module 


Start your program with the following: 





#! python3 

# mouseNow.py - Displays the mouse cursor's current position. 
import pyautogui 

print('Press Ctrl-C to quit. ') 

#TODO: Get and print the mouse coordinates. 





The beginning of the program imports the pyautogui module and prints 
a reminder to the user that they have to press CTRL-C to quit. 


Step 2: Set Up the Quit Code and Infinite Loop 


You can use an infinite while loop to constantly print the current mouse 
coordinates from mouse. position(). As for the code that quits the program, 
you'll need to catch the KeyboardInterrupt exception, which is raised when- 
ever the user presses CTRL-C. If you don’t handle this exception, it will dis- 
play an ugly traceback and error message to the user. Add the following to 
your program: 





#! python3 
# mouseNow.py - Displays the mouse cursor's current position. 
import pyautogui 
print('Press Ctrl-C to quit. ') 
try: 

while True: 

# TODO: Get and print the mouse coordinates. 

except KeyboardInterrupt: 

print('\nDone. ') 





To handle the exception, enclose the infinite while loop in a try state- 
ment. When the user presses CTRL-C, the program execution will move to 
the except clause @ and Done. will be printed in a new line ®. 


Step 3: Get and Print the Mouse Coordinates 


The code inside the while loop should get the current mouse coordinates, 
format them to look nice, and print them. Add the following code to the 
inside of the while loop: 


#! python3 
# mouseNow.py - Displays the mouse cursor's current position. 
import pyautogui 
print('Press Ctrl-C to quit.') 
--snip-- 
# Get and print the mouse coordinates. 
X, y = pyautogui.position() 
positionStr = 'X: ' + str(x).rjust(4) + ' Y: ' + str(y).rjust(4) 
--snip-- 





Using the multiple assignment trick, the x and y variables are given the 
values of the two integers returned in the tuple from pyautogui.position(). 
By passing x and y to the str() function, you can get string forms of the 
integer coordinates. The rjust() string method will right-justify them so 
that they take up the same amount of space, whether the coordinate has 
one, two, three, or four digits. Concatenating the right-justified string coor- 
dinates with 'X: ' and ' Y: ' labels gives us a neatly formatted string, which 
will be stored in positionStr. 

At the end of your program, add the following code: 





#! python3 
# mouseNow.py - Displays the mouse cursor's current position. 
--snip-- 
print(positionStr, end='') 
o print('\b' * len(positionStr), end='', flush=True) 





This actually prints positionStr to the screen. The end='' keyword argu- 
ment to print() prevents the default newline character from being added to 
the end of the printed line. It’s possible to erase text you’ve already printed 
to the screen—but only for the most recent line of text. Once you print a 
newline character, you can’t erase anything printed before it. 

To erase text, print the \b backspace escape character. This special 
character erases a character at the end of the current line on the screen. 
The line at © uses string replication to produce a string with as many \b 
characters as the length of the string stored in positionStr, which has the 
effect of erasing the positionStr string that was last printed. 

For a technical reason beyond the scope of this book, always pass 
flush=True to print() calls that print \b backspace characters. Otherwise, 
the screen might not update the text as desired. 

Since the while loop repeats so quickly, the user won’t actually notice 
that you're deleting and reprinting the whole number on the screen. For 
example, if the x-coordinate is 563 and the mouse moves one pixel to the 
right, it will look like only the 3 in 563 is changed to a 4. 

When you run the program, there will be only two lines printed. They 
should look like something like this: 


Press Ctrl-C to quit. 
X: 290 Y: 424 





The first line displays the instruction to press CTRL-C to quit. The sec- 
ond line with the mouse coordinates will change as you move the mouse 
around the screen. Using this program, you'll be able to figure out the 
mouse coordinates for your GUI automation scripts. 


Controlling Mouse Interaction 


Now that you know how to move the mouse and figure out where it is on the 
screen, you're ready to start clicking, dragging, and scrolling. 
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Clicking the Mouse 


To send a virtual mouse click to your computer, call the pyautogui.click() 
method. By default, this click uses the left mouse button and takes place 
wherever the mouse cursor is currently located. You can pass x- and 
y-coordinates of the click as optional first and second arguments if you 
want it to take place somewhere other than the mouse’s current position. 

If you want to specify which mouse button to use, include the button 
keyword argument, with a value of 'left', 'middle', or 'right'. For example, 
pyautogui.click(100, 150, button="left') will click the left mouse button at 
the coordinates (100, 150), while pyautogui.click(200, 250, button='right' ) 
will perform a right-click at (200, 250). 

Enter the following into the interactive shell: 





>>> import pyautogui 
>>> pyautogui.click(10, 5) 


You should see the mouse pointer move to near the top-left corner of 
your screen and click once. A full “click” is defined as pushing a mouse 
button down and then releasing it back up without moving the cursor. You 
can also perform a click by calling pyautogui.mouseDown(), which only pushes 
the mouse button down, and pyautogui.mouseUp(), which only releases the but- 
ton. These functions have the same arguments as click(), and in fact, the 
click() function is just a convenient wrapper around these two function calls. 

As a further convenience, the pyautogui.doubleClick() function will per- 
form two clicks with the left mouse button, while the pyautogui.rightClick() 
and pyautogui.middleClick() functions will perform a click with the right and 
middle mouse buttons, respectively. 


Dragging the Mouse 


Dragging means moving the mouse while holding down one of the mouse 
buttons. For example, you can move files between folders by dragging the 
folder icons, or you can move appointments around in a calendar app. 

PyAutoGUI provides the pyautogui.dragTo() and pyautogui.dragRel() 
functions to drag the mouse cursor to a new location or a location rela- 
tive to its current one. The arguments for dragTo() and dragRel() are the 
same as moveTo() and moveRel(): the x-coordinate/horizontal movement, the 
y-coordinate/vertical movement, and an optional duration of time. (OS X 
does not drag correctly when the mouse moves too quickly, so passing a 
duration keyword argument is recommended.) 

To try these functions, open a graphics-drawing application such as 
Paint on Windows, Paintbrush on OS X, or GNU Paint on Linux. (If you 
don’t have a drawing application, you can use the online one at http:// 
sumopaint.com/.) I will use PyAutoGUI to draw in these applications. 
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With the mouse cursor over the drawing application’s canvas and the 
Pencil or Brush tool selected, enter the following into a new file editor win- 
dow and save it as spiralDraw.py: 





import pyautogui, time 
time.sleep(5) 
pyautogui.click() # click to put drawing program in focus 
distance = 200 
while distance > 0: 
pyautogui.dragRel(distance, 0, duration=0.2) # move right 
distance = distance - 5 
pyautogui.dragRel(0, distance, duration=0.2) # move down 
pyautogui.dragRel(-distance, 0, duration=0.2) # move left 
distance = distance - 5 
pyautogui.dragRel(0, -distance, duration=0.2) # move up 





When you run this program, there will be a five-second delay ® for 
you to move the mouse cursor over the drawing program’s window with the 
Pencil or Brush tool selected. Then spiralDraw.py will take control of the 
mouse and click to put the drawing program in focus @. A window is in 
focus when it has an active blinking cursor, and the actions you take—like 
typing or, in this case, dragging the mouse—will affect that window. Once 
the drawing program is in focus, spiralDraw.py draws a square spiral pattern 
like the one in Figure 18-2. 





Home View 
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Clipboard Image | Tools | Brushes | Shapes, Size Colors 
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Figure 18-2: The results from the pyautogui.dragRel() example 
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The distance variable starts at 200, so on the first iteration of the while 
loop, the first dragRel() call drags the cursor 200 pixels to the right, taking 
0.2 seconds ®. distance is then decreased to 195 @, and the second dragRel() 
call drags the cursor 195 pixels down ®. The third dragRel() call drags the 
cursor —195 horizontally (195 to the left) @, distance is decreased to 190, 
and the last dragRel() call drags the cursor 190 pixels up. On each iteration, 
the mouse is dragged right, down, left, and up, and distance is slightly smaller 
than it was in the previous iteration. By looping over this code, you can move 
the mouse cursor to draw a square spiral. 

You could draw this spiral by hand (or rather, by mouse), but you’d 
have to work slowly to be so precise. PyAutoGUI can do it in a few seconds! 


You could have your code draw the image using the pillow module’s drawing func- 
tions—see Chapter 17 for more information. But using GUI automation allows you 
to make use of the advanced drawing tools that graphics programs can provide, such 
as gradients, different brushes, or the fill bucket. 


Scrolling the Mouse 


The final PyAutoGUI mouse function is scroll(), which you pass an integer 
argument for how many units you want to scroll the mouse up or down. The 
size of a unit varies for each operating system and application, so you'll have 
to experiment to see exactly how far it scrolls in your particular situation. 
The scrolling takes place at the mouse cursor’s current position. Passing a 
positive integer scrolls up, and passing a negative integer scrolls down. Run 
the following in IDLE ’s interactive shell while the mouse cursor is over the 
IDLE window: 





>>> pyautogui.scrol1(200) 





You'll see IDLE briefly scroll upward—and then go back down. The 
downward scrolling happens because IDLE automatically scrolls down to 
the bottom after executing an instruction. Enter this code instead: 





>>> import pyperclip 
>>> numbers = '' 
>>> for i in range(200): 
numbers = numbers + str(i) + '\n' 


>>> pyperclip.copy(numbers) 





This imports pyperclip and sets up an empty string, numbers. The 
code then loops through 200 numbers and adds each number to numbers, 
along with a newline. After pyperclip.copy(numbers), the clipboard will be 
loaded with 200 lines of numbers. Open a new file editor window and 
paste the text into it. This will give you a large text window to try scroll- 
ing in. Enter the following code into the interactive shell: 





>>> import time, pyautogui 
>>> time.sleep(5); pyautogui.scroll(100) 





On the second line, you enter two commands separated by a semicolon, 
which tells Python to run the commands as if they were on separate lines. 
The only difference is that the interactive shell won’t prompt you for input 
between the two instructions. This is important for this example because 
we want to the call to pyautogui.scroll() to happen automatically after the 
wait. (Note that while putting two commands on one line can be useful in 
the interactive shell, you should still have each instruction on a separate 
line in your programs.) 

After pressing ENTER to run the code, you will have five seconds to 
click the file editor window to put it in focus. Once the pause is over, the 
pyautogui.scroll() call will cause the file editor window to scroll up after 
the five-second delay. 


Working with the Screen 


Your GUI automation programs don’t have to click and type blindly. 
PyAutoGUI has screenshot features that can create an image file based on 
the current contents of the screen. These functions can also return a Pillow 
Image object of the current screen’s appearance. If you’ve been skipping 
around in this book, you’ll want to read Chapter 17 and install the pillow 
module before continuing with this section. 

On Linux computers, the scrot program needs to be installed to use 
the screenshot functions in PyAutoGUI. In a Terminal window, run sudo 
apt-get install scrot to install this program. If you’re on Windows or OS X, 
skip this step and continue with the section. 


Getting a Screenshot 


To take screenshots in Python, call the pyautogui.screenshot() function. 
Enter the following into the interactive shell: 





>>> import pyautogui 
>>> im = pyautogui.screenshot() 





The im variable will contain the Image object of the screenshot. You can 
now call methods on the Image object in the im variable, just like any other 
Image object. Enter the following into the interactive shell: 





>>> im.getpixel((0, 0)) 
(176, 176, 175) 

>>> im.getpixel((50, 200)) 
(130, 135, 144) 





Pass getpixel() a tuple of coordinates, like (0, 0) or (50, 200), and iť’ ll 
tell you the color of the pixel at those coordinates in your image. The return 
value from getpixel() is an RGB tuple of three integers for the amount of 
red, green, and blue in the pixel. (There is no fourth value for alpha, because 
screenshot images are fully opaque.) This is how your programs can “see” 
what is currently on the screen. 
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Analyzing the Screenshot 


Say that one of the steps in your GUI automation program is to click a gray 
button. Before calling the click() method, you could take a screenshot and 
look at the pixel where the script is about to click. If it’s not the same gray 
as the gray button, then your program knows something is wrong. Maybe 
the window moved unexpectedly, or maybe a pop-up dialog has blocked the 
button. At this point, instead of continuing—and possibly wreaking havoc 
by clicking the wrong thing—your program can “see” that it isn’t clicking 
on the right thing and stop itself. 

PyAutoGUI’s pixelMatchesColor() function will return True if the pixel at 
the given x- and y-coordinates on the screen matches the given color. The 
first and second arguments are integers for the x- and y-coordinates, and 
the third argument is a tuple of three integers for the RGB color the screen 
pixel must match. Enter the following into the interactive shell: 





>>> import pyautogui 

>>> im = pyautogui.screenshot() 

>>> im.getpixel((50, 200)) 

(130, 135, 144) 

>>> pyautogui.pixelMatchesColor(50, 200, (130, 135, 144)) 
True 

>>> pyautogui.pixelMatchesColor(50, 200, (255, 135, 144)) 
False 





After taking a screenshot and using getpixel() to get an RGB tuple for 
the color of a pixel at specific coordinates ®, pass the same coordinates 
and RGB tuple to pixelMatchesColor() @, which should return True. Then 
change a value in the RGB tuple and call pixelMatchesColor() again for the 
same coordinates ®. This should return false. This method can be useful 
to call whenever your GUI automation programs are about to call click(). 
Note that the color at the given coordinates must exactly match. If it is even 
slightly different—for example, (255, 255, 254) instead of (255, 255, 255)— 
then pixelMatchesColor() will return False. 


Project: Extending the mouseNow Program 
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You could extend the mouseNow.py project from earlier in this chapter so 
that it not only gives the x- and y-coordinates of the mouse cursor’s current 
position but also gives the RGB color of the pixel under the cursor. Modify 
the code inside the while loop of mouseNow.py to look like this: 





#! python3 

# mouseNow.py - Displays the mouse cursor's current position. 

--snip-- 
positionStr = 'X: ' + str(x).rjust(4) + ' Y: ' + str(y).rjust(4) 
pixelColor = pyautogui.screenshot().getpixel((x, y)) 
positionStr += ' RGB: (' + str(pixelColor[0]).rjust(3) 
positionStr += ', ' + str(pixelColor[1]).rjust(3) 


positionStr += ', ' + str(pixelColor[2]).rjust(3) + ')' 


print(positionStr, end='') 
--snip-- 





Now, when you run mouseNow.py, the output will include the RGB color 
value of the pixel under the mouse cursor. 





Press Ctrl-C to quit. 
X: 406 Y: 17 RGB: (161, 50, 50) 





This information, along with the pixelMatchesColor() function, should 
make it easy to add pixel color checks to your GUI automation scripts. 


Image Recognition 


But what if you do not know beforehand where PyAutoGUI should click? 
You can use image recognition instead. Give PyAutoGUI an image of what 
you want to click and let it figure out the coordinates. 

For example, if you have previously taken a screenshot to capture the 
image of a Submit button in submit.png, the locateOnScreen() function will 
return the coordinates where that image is found. To see how locateOnScreen() 
works, try taking a screenshot of a small area on your screen; then save the 
image and enter the following into the interactive shell, replacing ‘submit. 
png' with the filename of your screenshot: 





>>> import pyautogui 
>>> pyautogui. locateOnScreen('submit.png' ) 
(643, 745, 70, 29) 





The four-integer tuple that locateOnScreen() returns has the x-coordinate 
of the left edge, the y-coordinate of the top edge, the width, and the height 
for the first place on the screen the image was found. If you're trying this 
on your computer with your own screenshot, your return value will be dif- 
ferent from the one shown here. 

If the image cannot be found on the screen, locateOnScreen() will 
return None. Note that the image on the screen must match the provided 
image perfectly in order to be recognized. If the image is even a pixel off, 
locateOnScreen() will return None. 

If the image can be found in several places on the screen, 
locateAll0nScreen() will return a Generator object, which can be passed 
to list() to return a list of four-integer tuples. There will be one four- 
integer tuple for each location where the image is found on the screen. 
Continue the interactive shell example by entering the following (and 
replacing 'submit.png' with your own image filename): 





>>> list (pyautogui.locateAl110nScreen('submit.png' )) 
[(643, 745, 70, 29), (1007, 801, 70, 29)] 
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Each of the four-integer tuples represents an area on the screen. If your 
image is only found in one area, then using list() and locateAll0nScreen() 
just returns a list containing one tuple. 

Once you have the four-integer tuple for the area on the screen where 
your image was found, you can click the center of this area by passing the 
tuple to the center() function to return x- and y-coordinates of the area’s 
center. Enter the following into the interactive shell, replacing the argu- 
ments with your own filename, four-integer tuple, and coordinate pair: 


>>> pyautogui. locateOnScreen('submit.png' ) 
(643, 745, 70, 29) 

>>> pyautogui.center((643, 745, 70, 29)) 
(678, 759) 

>>> pyautogui.click((678, 759)) 





Once you have center coordinates from center(), passing the coor- 
dinates to click() should click the center of the area on the screen that 
matches the image you passed to locateOnScreen(). 


Controlling the Keyboard 
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PyAutoGUI also has functions for sending virtual keypresses to your com- 
puter, which enables you to fill out forms or enter text into applications. 


Sending a String from the Keyboard 


The pyautogui.typewrite() function sends virtual keypresses to the computer. 
What these keypresses do depends on what window and text field have focus. 
You may want to first send a mouse click to the text field you want in order 
to ensure that it has focus. 

As a simple example, lets use Python to automatically type the words 
Hello world! into a file editor window. First, open a new file editor window 
and position it in the upper-left corner of your screen so that PyAutoGUI 
will click in the right place to bring it into focus. Next, enter the following 
into the interactive shell: 


>>> pyautogui.click(100, 100); pyautogui.typewrite('Hello world!') 


Notice how placing two commands on the same line, separated by 
a semicolon, keeps the interactive shell from prompting you for input 
between running the two instructions. This prevents you from acciden- 
tally bringing a new window into focus between the click() and typewrite() 
calls, which would mess up the example. 

Python will first send a virtual mouse click to the coordinates (100, 100), 
which should click the file editor window and put it in focus. The typewrite() 
call will send the text Hello world! to the window, making it look like Fig- 
ure 18-3. You now have code that can type for you! 
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>>> import pyautogui 
>>> pyautogui.click('left', 100, 100); pyautogui.typewrite('Hello world!") 
>>> 








Figure 18-3: Using PyAutogGUI to click the file editor window and type Hello world! into it 


By default, the typewrite() function will type the full string instantly. 
However, you can pass an optional second argument to add a short pause 
between each character. This second argument is an integer or float value 
of the number of seconds to pause. For example, pyautogui.typewrite( ‘Hello 
world!', 0.25) will wait a quarter-second after typing H, another quarter- 
second after e, and so on. This gradual typewriter effect may be useful for 
slower applications that can’t process keystrokes fast enough to keep up 
with PyAutoGUI. 

For characters such as A or !, PyAutoGUI will automatically simulate 
holding down the SHIFT key as well. 


Key Names 


Not all keys are easy to represent with single text characters. For example, 
how do you represent SHIFT or the left arrow key as a single character? In 
PyAutoGUI, these keyboard keys are represented by short string values 
instead: 'esc' for the ESC key or ‘enter’ for the ENTER key. 

Instead of a single string argument, a list of these keyboard key strings 
can be passed to typewrite(). For example, the following call presses the A 
key, then the B key, then the left arrow key twice, and finally the X and Y keys: 





>>> pyautogui.typewrite(['a', 'b', ‘left’, ‘left’, 'X', 'Y']) 





Because pressing the left arrow key moves the keyboard cursor, this will 
output XYab. Table 18-1 lists the PyAutoGUI keyboard key strings that you 
can pass to typewrite() to simulate pressing any combination of keys. 

You can also examine the pyautogui.KEYBOARD_KEYS list to see all possible 
keyboard key strings that PyAutoGUI will accept. The 'shift' string refers 
to the left SHIFT key and is equivalent to 'shiftleft'. The same applies for 
‘ctrl', 'alt', and 'win' strings; they all refer to the left-side key. 
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Table 18-1: Pykeyboard Attributes 
Keyboard key string 
BO pe Dj Seep A eB phn E SDE S; 
'1', '@', '#', and so on 
'enter' (or 'return' or '\n') 
'esc' 
'shiftleft', 'shiftright' 
'altleft', 'altright' 
'ctrlleft', 'ctrlright' 
'tab' (or '\t') 
'backspace', 'delete' 
'pageup', 'pagedown' 
'home', 'end' 
'up', 'down', 'left', 'right' 
'f1', 'f2', 'f3', and so on 


'volumemute', 'volumedown', 'volumeup' 


' pause ' 


'capslock', 'numlock', 'scrolllock' 


'insert' 
'printscreen' 
'winleft', 'winright' 
' command ' 


‘option' 


Pressing and Releasing the Keyboard 


Meaning 


The keys for single characters 


The ENTER key 

The ESC key 

The left and right SHIFT keys 

The left and right ALT keys 

The left and right CTRL keys 

The TAB key 

The BACKSPACE and DELETE keys 
The PAGE UP and PAGE DOWN keys 
The HOME and END keys 

The up, down, left, and right arrow keys 
The F1 to F12 keys 


The mute, volume down, and volume up 
keys (some keyboards do not have these 
keys, but your operating system will still 
be able to understand these simulated 
keypresses) 


The PAUSE key 


The CAPS LOCK, NUM LOCK, and SCROLL 
LOCK keys 


The INS or INSERT key 

The PRTSC or PRINT SCREEN key 

The left and right WIN keys (on Windows) 
The Command (8) key (on OS X) 

The OPTION key (on OS X) 


Much like the mouseDown() and mouseUp() functions, pyautogui.keyDown() and 
pyautogui.keyUp() will send virtual keypresses and releases to the computer. 
They are passed a keyboard key string (see Table 18-1) for their argument. 
For convenience, PyAutoGUI provides the pyautogui.press() function, which 
calls both of these functions to simulate a complete keypress. 

Run the following code, which will type a dollar sign character (obtained 
by holding the SHIFT key and pressing 4): 





>>> pyautogui.keyDown('shift'); pyautogui.press('4'); pyautogui.keyUp('shift') 





© 


This line presses down SHIFT, presses (and releases) 4, and then releases 
SHIFT. If you need to type a string into a text field, the typewrite() function 
is more suitable. But for applications that take single-key commands, the 
press() function is the simpler approach. 


Hotkey Combinations 


A hotkey or shortcutis a combination of keypresses to invoke some applica- 
tion function. The common hotkey for copying a selection is CTRL-C (on 
Windows and Linux) or #-C (on OS X). The user presses and holds the 
CTRL key, then presses the C key, and then releases the C and CTRL keys. To 
do this with PyAutoGUI’s keyDown() and keyUp() functions, you would have 
to enter the following: 





pyautogui.keyDown('ctr1') 
pyautogui.keyDown('c' 
pyautogui.keyUp('c') 
pyautogui.keyUp('ctrl') 





This is rather complicated. Instead, use the pyautogui.hotkey() func- 
tion, which takes multiple keyboard key string arguments, presses them in 
order, and releases them in the reverse order. For the CTRL-C example, the 
code would simply be as follows: 





pyautogui.hotkey('ctrl', 'c') 





This function is especially useful for larger hotkey combinations. In 
Word, the CTRL-ALT-SHIFT-S hotkey combination displays the Style pane. 
Instead of making eight different function calls (four keyDown() calls and 
four keyUp() calls), you can just call hotkey('ctrl', ‘alt', 'shift', 's'). 

With a new IDLE file editor window in the upper-left corner of your 
screen, enter the following into the interactive shell (in OS X, replace 'alt' 
with 'ctrl'): 





>>> import pyautogui, time 
>>> def commentAfterDelay(): 
pyautogui.click(100, 100) 
pyautogui.typewrite('In IDLE, Alt-3 comments out a line.') 
time.sleep(2) 
pyautogui.hotkey('alt', '3') 


>>> commentAfterDelay() 





This defines a function commentAfterDelay() that, when called, will click 
the file editor window to bring it into focus ®, type In IDLE, Atl-3 comments 
out a line @, pause for 2 seconds, and then simulate pressing the ALT-3 hot- 
key (or CTRL-3 on OS X) ©. This keyboard shortcut adds two # characters 
to the current line, commenting it out. (This is a useful trick to know when 
writing your own code in IDLE.) 
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Review of the PyAutoGUI Functions 


Since this chapter covered many different functions, here is a quick sum- 
mary reference: 
moveTo(x, y) Moves the mouse cursor to the given x and y coordinates. 


moveRel(x0ffset, yOffset) Moves the mouse cursor relative to its cur- 
rent position. 


dragTo(x, y) Moves the mouse cursor while the left button is held down. 


dragRel(x0ffset, yOffset) Moves the mouse cursor relative to its cur- 
rent position while the left button is held down. 


click(x, y, button) Simulates a click (left button by default). 
rightClick() Simulates a right-button click. 

middleClick() Simulates a middle-button click. 

doubleClick() Simulates a double left-button click. 


mouseDown(x, y, button) Simulates pressing down the given button at 
the position x, y. 


mouseUp(x, y, button) Simulates releasing the given button at the 
position x, y. 

scroll(units) Simulates the scroll wheel. A positive argument scrolls 
up; a negative argument scrolls down. 


typewrite(message) Types the characters in the given message string. 
typewrite([key1, key2, key3]) Types the given keyboard key strings. 
press(key) Presses the given keyboard key string. 

keyDown(key) Simulates pressing down the given keyboard key. 
keyUp(key) Simulates releasing the given keyboard key. 


hotkey([key1, key2, key3]) Simulates pressing the given keyboard key 
strings down in order and then releasing them in reverse order. 


screenshot() Returns a screenshot as an Image object. (See Chapter 17 
for information on Image objects.) 


Project: Automatic Form Filler 
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Of all the boring tasks, filling out forms is the most dreaded of chores. It’s 
only fitting that now, in the final chapter project, you will slay it. Say you 
have a huge amount of data in a spreadsheet, and you have to tediously 
retype it into some other application’s form interface—with no intern to do 
it for you. Although some applications will have an Import feature that will 
allow you to upload a spreadsheet with the information, sometimes it seems 
that there is no other way than mindlessly clicking and typing for hours 

on end. You’ve come this far in this book; you know that of course there’s 
another way. 


The form for this project is a Google Docs form that you can find at 
http://nostarch.com/automatestuff. It looks like Figure 18-4. 


EB Generic Form 
e CŒ https://docs.google.com/spreadsheet/viewform?fromEn @ 14 Ye © D. F @ Gre 


Generic Form 

This form is for the GUI automation project from Chapter 18 of "Automate the Boring Stuff with 
Python", available at http://automatetheboringstuff.com. 

* Required 


Name * 


vane 


Greatest Fear(s) 


What is the source of your wizard powers? 
Wand S 


Robocop was the greatest action movie of the 1980s. 
Be 2e 3 AS 


Strongly Disagree Strongly Agree 


Additional Comments 





| Submit 
Never submit passwords through Google Forms. 








Figure 18-4: The form used for this project 


Ata high level, here’s what your program should do: 


e Click the first text field of the form. 

e Move through the form, typing information into each field. 
e Click the Submit button. 

e Repeat the process with the next set of data. 


This means your code will need to do the following: 


e Call pyautogui.click() to click the form and Submit button. 
e Call pyautogui.typewrite() to enter text into the fields. 


e Handle the KeyboardInterrupt exception so the user can press CTRL-C 
to quit. 


Open a new file editor window and save it as formFiller.py. 
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Step 1: Figure Out the Steps 


Before writing code, you need to figure out the exact keystrokes and mouse 
clicks that will fill out the form once. The mouseNow.py script on page 417 
can help you figure out specific mouse coordinates. You need to know only 
the coordinates of the first text field. After clicking the first field, you can 
just press TAB to move focus to the next field. This will save you from having 
to figure out the x- and y-coordinates to click for every field. 

Here are the steps for entering data into the form: 


1. Click the Name field. (Use mouseNow.py to determine the coordinates 
after maximizing the browser window. On OS X, you may need to click 
twice: once to put the browser in focus and again to click the Name 
field.) 


Type a name and then press TAB. 
3. Type a greatest fear and then press TAB. 


Press the down arrow key the correct number of times to select the 
wizard power source: once for wand, twice for amulet, three times for 
crystal ball, and four times for money. Then press TAB. (Note that on 
OS X, you will have to press the down arrow key one more time for 
each option. For some browsers, you may need to press the ENTER key 
as well.) 


5. Press the right arrow key to select the answer to the RoboCop question. 
Press it once for 2, twice for 3, three times for 4, or four times for 5; 
or just press the spacebar to select J (which is highlighted by default). 
Then press TAB. 


6. Type an additional comment and then press TAB. 
Press the ENTER key to “click” the Submit button. 


8. After submitting the form, the browser will take you to a page where 
you will need to click a link to return to the form page. 


Note that if you run this program again later, you may have to update 
the mouse click coordinates, since the browser window might have changed 
position. To work around this, always make sure the browser window is max- 
imized before finding the coordinates of the first form field. Also, different 
browsers on different operating systems might work slightly differently from 
the steps given here, so check that these keystroke combinations work for 
your computer before running your program. 


Step 2: Set Up Coordinates 


Load the example form you downloaded (Figure 18-4) in a browser and max- 
imize your browser window. Open a new Terminal or command line window 
to run the mouseNow.py script, and then mouse over the Name field to fig- 
ure out its the x- and y-coordinates. These numbers will be assigned to the 
nameField variable in your program. Also, find out the x- and y-coordinates 
and RGB tuple value of the blue Submit button. These values will be assigned 
to the submitButton and submitButtonColor variables, respectively. 


Next, fill in some dummy data for the form and click Submit. You need 
to see what the next page looks like so that you can use mouseNow.py to find 
the coordinates of the Submit another response link on this new page. 

Make your source code look like the following, being sure to replace all 
the values in italics with the coordinates you determined from your own tests: 





#! python3 
# formFiller.py - Automatically fills in the form. 


import pyautogui, time 

# Set these to the correct coordinates for your computer. 
nameField = (648, 319) 

submitButton = (651, 817) 

submitButtonColor = (75, 141, 249) 
submitAnotherLink = (760, 224) 

# TODO: Give the user a chance to kill the script. 
# TODO: Wait until the form page has loaded. 

# TODO: Fill out the Name Field. 

# TODO: Fill out the Greatest Fear(s) field. 

# TODO: Fill out the Source of Wizard Powers field. 
# TODO: Fill out the RoboCop field. 

# TODO: Fill out the Additional Comments field. 

# TODO: Click Submit. 


# TODO: Wait until form page has loaded. 


# TODO: Click the Submit another response link. 





Now you need the data you actually want to enter into this form. In the 
real world, this data might come from a spreadsheet, a plaintext file, or a 
website, and it would require additional code to load into the program. But 
for this project, you'll just hardcode all this data in a variable. Add the fol- 
lowing to your program: 





#! python3 
# formFiller.py - Automatically fills in the form. 


--snip-- 
formData = [{'name': 'Alice', 'fear': 'eavesdroppers', ‘source’: ‘wand’, 
‘robocop’: 4, ‘comments’: 'Tell Bob I said hi.'}, 


{'name': 'Bob', 'fear': 'bees', ‘source’: ‘amulet’, ‘robocop’: 4, 
‘comments’: 'n/a'}, 
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{'name': 'Carol', 'fear': 'puppets', ‘source’: ‘crystal ball’, 
‘robocop’: 1, ‘'comments': 'Please take the puppets out of the 
break room.'}, 

{'name': 'Alex Murphy’, 'fear': 'ED-209', ‘source’: ‘money’, 
‘robocop’: 5, ‘comments’: 'Protect the innocent. Serve the public 
trust. Uphold the law.'}, 


--snip-- 





The formData list contains four dictionaries for four different names. 
Each dictionary has names of text fields as keys and responses as values. 
The last bit of setup is to set PyAutoGUI’s PAUSE variable to wait half a sec- 
ond after each function call. Add the following to your program after the 
formData assignment statement: 





pyautogui.PAUSE = 0.5 





Step 3: Start Typing Data 


A for loop will iterate over each of the dictionaries in the formData list, 
passing the values in the dictionary to the PyAutoGUI functions that will 
virtually type in the text fields. 

Add the following code to your program: 





#! python3 
# formFiller.py - Automatically fills in the form. 


--snip-- 


for person in formData: 
# Give the user a chance to kill the script. 
print('>>> 5 SECOND PAUSE TO LET USER PRESS CTRL-C <<<") 
time.sleep(5) 


# Wait until the form page has loaded. 
while not pyautogui.pixelMatchesColor(submitButton[0], submitButton[1], 
submitButtonColor): 

time.sleep(0.5) 


--snip-- 





As a small safety feature, the script has a five-second pause ® that gives 
the user a chance to hit CTRL-C (or move the mouse cursor to the upper- 
left corner of the screen to raise the FailSafeException exception) to shut 
the program down in case it’s doing something unexpected. Then the pro- 
gram waits until the Submit button’s color is visible @, letting the program 
know that the form page has loaded. Remember that you figured out the 


© 
@ 


coordinate and color information in step 2 and stored it in the submitButton 
and submitButtonColor variables. To use pixelMatchesColor(), you pass the coor- 
dinates submitButton[0] and submitButton[1], and the color submitButtonColor. 

After the code that waits until the Submit button’s color is visible, add 
the following: 





#! python3 
# formFiller.py - Automatically fills in the form. 


--snip-- 


print('Entering %s info...' % (person['name'])) 
pyautogui.click(nameField[0], nameField[1]) 


# Fill out the Name field. 
pyautogui.typewrite(person['name'] + '\t') 


# Fill out the Greatest Fear(s) field. 
pyautogui.typewrite(person['fear'] + '\t') 


--snip-- 





We add an occasional print() call to display the program’s status in its 
Terminal window to let the user know what’s going on @. 

Since the program knows that the form is loaded, it’s time to call click() 
to click the Name field @ and typewrite() to enter the string in person['name' ] 
©. The '\t' character is added to the end of the string passed to typewrite() 
to simulate pressing TAB, which moves the keyboard focus to the next 
field, Greatest Fear(s). Another call to typewrite() will type the string in 
person['fear'] into this field and then tab to the next field in the form 9. 


Step 4: Handle Select Lists and Radio Buttons 


The drop-down menu for the “wizard powers” question and the radio but- 
tons for the RoboCop field are trickier to handle than the text fields. To 
click these options with the mouse, you would have to figure out the x- and 
y-coordinates of each possible option. It’s easier to use the keyboard arrow 
keys to make a selection instead. 

Add the following to your program: 





#! python3 
# formFiller.py - Automatically fills in the form. 


--snip-- 
# Fill out the Source of Wizard Powers field. 


if person['source'] == ‘wand’: 
pyautogui.typewrite(['down', '\t']) 
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elif person['source'] == ‘amulet’: 
pyautogui.typewrite(['down', ‘down’, '\t']) 


elif person['source'] == ‘crystal ball’: 
pyautogui.typewrite(['down', ‘down’, ‘down’, '\t']) 
elif person['source'] == 'money': 


pyautogui.typewrite(['down', ‘down’, ‘down’, ‘down’, '\t']) 


# Fill out the RoboCop field. 
if person['robocop'] == 1: 
pyautogui.typewrite([' ', ‘\t']) 
elif person['robocop'] == 2: 
pyautogui.typewrite(['right', '\t']) 
elif person['robocop'] == 3: 
pyautogui.typewrite(['right', ‘right’, '\t']) 
elif person['robocop'] == 4: 
pyautogui. typewrite([' ee ‘right’, ‘right’, '\t']) 
elif person['robocop'] == 5: 
pyautogui. typenrite([' sie: » ‘vight', 'right', ‘right’, '\t']) 


(A 


--snip-- 





Once the drop-down menu has focus (remember that you wrote code 
to simulate pressing TAB after filling out the Greatest Fear(s) field), press- 
ing the down arrow key will move to the next item in the selection list. 
Depending on the value in person['source'], your program should send a 
number of down arrow keypresses before tabbing to the next field. If the 
value at the ‘source’ key in this user’s dictionary is 'wand' ®, we simulate 
pressing the down arrow key once (to select Wand) and pressing TAB @. 

If the value at the 'source' key is 'amulet', we simulate pressing the down 
arrow key twice and pressing TAB, and so on for the other possible answers. 

The radio buttons for the RoboCop question can be selected with the 
right arrow keys—or, if you want to select the first choice ®, by just pressing 
the spacebar @. 


Step 5: Submit the Form and Wait 


You can fill out the Additional Comments field with the typewrite() func- 
tion by passing person['comments'] as an argument. You can type an addi- 
tional '\t' to move the keyboard focus to the next field or the Submit 
button. Once the Submit button is in focus, calling pyautogui.press('enter' ) 
will simulate pressing the ENTER key and submit the form. After submitting 
the form, your program will wait five seconds for the next page to load. 

Once the new page has loaded, it will have a Submit another response link 
that will direct the browser to a new, empty form page. You stored the coor- 
dinates of this link as a tuple in submitAnotherLink in step 2, so pass these 
coordinates to pyautogui.click() to click this link. 

With the new form ready to go, the script’s outer for loop can continue 
to the next iteration and enter the next person’s information into the form. 
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Complete your program by adding the following code: 





#! python3 
# formFiller.py - Automatically fills in the form. 


--snip-- 


# Fill out the Additional Comments field. 
pyautogui.typewrite(person['comments'] + '\t') 


# Click Submit. 
pyautogui.press('enter') 


# Wait until form page has loaded. 
print('Clicked Submit. ') 
time.sleep(5) 


# Click the Submit another response link. 
pyautogui.click(submitAnotherLink[0], submitAnotherLink[1]) 





Once the main for loop has finished, the program will have plugged 
in the information for each person. In this example, there are only four 
people to enter. But if you had 4,000 people, then writing a program to do 
this would save you a lot of time and typing! 


Summary 


GUI automation with the pyautogui module allows you to interact with 
applications on your computer by controlling the mouse and keyboard. 
While this approach is flexible enough to do anything that a human user 
can do, the downside is that these programs are fairly blind to what they are 
clicking or typing. When writing GUI automation programs, try to ensure 
that they will crash quickly if they’re given bad instructions. Crashing is 
annoying, but it’s much better than the program continuing in error. 

You can move the mouse cursor around the screen and simulate mouse 
clicks, keystrokes, and keyboard shortcuts with PyAutoGUI. The pyautogui 
module can also check the colors on the screen, which can provide your 
GUI automation program with enough of an idea of the screen contents to 
know whether it has gotten offtrack. You can even give PyAutoGUI a screen- 
shot and let it figure out the coordinates of the area you want to click. 

You can combine all of these PyAutoGUI features to automate any 
mindlessly repetitive task on your computer. In fact, it can be downright 
hypnotic to watch the mouse cursor move on its own and see text appear 
on the screen automatically. Why not spend the time you saved by sitting 
back and watching your program do all your work for you? There’s a certain 
satisfaction that comes from seeing how your cleverness has saved you from 
the boring stuff. 
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Practice Questions 


1. How can you trigger PyAutoGUI’s fail safe to stop a program? 

2. What function returns the current resolution()? 

3. What function returns the coordinates for the mouse cursor’s current 
position? 

What is the difference between pyautogui.moveTo() and pyautogui.moveRel()? 
What functions can be used to drag the mouse? 


What function call will type out the characters of "Hello world!"? 


SPA Se 


How can you do keypresses for special keys such as the keyboard’s left 

arrow key? 

8. How can you save the current contents of the screen to an image file 
named screenshot.png? 

9. What code would set a two second pause after every PyAutoGUI func- 

tion call? 


Practice Projects 
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For practice, write programs that do the following. 


Looking Busy 


Many instant messaging programs determine whether you are idle, or away 
from your computer, by detecting a lack of mouse movement over some 
period of time—say, ten minutes. Maybe you'd like to sneak away from 
your desk for a while but don’t want others to see your instant messenger 
status go into idle mode. Write a script to nudge your mouse cursor slightly 
every ten seconds. The nudge should be small enough so that it won’t get in 
the way if you do happen to need to use your computer while the script is 
running. 


Instant Messenger Bot 


Google Talk, Skype, Yahoo Messenger, AIM, and other instant messag- 

ing applications often use proprietary protocols that make it difficult for 
others to write Python modules that can interact with these programs. But 
even these proprietary protocols can’t stop you from writing a GUI auto- 
mation tool. 

The Google Talk application has a search bar that lets you enter a 
username on your friend list and open a messaging window when you press 
ENTER. The keyboard focus automatically moves to the new window. Other 
instant messenger applications have similar ways to open new message 
windows. Write a program that will automatically send out a notification 
message to a select group of people on your friend list. Your program may 
have to deal with exceptional cases, such as friends being offline, the chat 
window appearing at different coordinates on the screen, or confirmation 


boxes that interrupt your messaging. Your program will have to take screen- 
shots to guide its GUI interaction and adopt ways of detecting when its vir- 
tual keystrokes aren’t being sent. 


You may want to set up some fake test accounts so that you don't accidentally spam 
your real friends while writing this program. 


Game-Playing Bot Tutorial 


There is a great tutorial titled “How to Build a Python Bot That Can Play 
Web Games” that you can find at http://nostarch.com/automatestuff/. This 
tutorial explains how to create a GUI automation program in Python that 
plays a Flash game called Sushi Go Round. The game involves clicking the 
correct ingredient buttons to fill customers’ sushi orders. The faster you fill 
orders without mistakes, the more points you get. This is a perfectly suited 
task for a GUI automation program—and a way to cheat to a high score! 
The tutorial covers many of the same topics that this chapter covers but also 
includes descriptions of PyAutoGUT’s basic image recognition features. 
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INSTALLING 
THIRD-PARTY MODULES 





Beyond the standard library of modules 
E>) packaged with Python, other developers 
N74 : : 
b have written their own modules to extend 
Python’s capabilities even further. The primary 
way to install third-party modules is to use Python’s 
pip tool. This tool securely downloads and installs 


Python modules onto your computer from Attps://pypi.python.org/, the web- 
site of the Python Software Foundation. PyPI, or the Python Package Index, 
is a sort of free app store for Python modules. 






The pip Tool 


The executable file for the pip tool is called pip on Windows and pip3 on OS X 
and Linux. On Windows, you can find pip at C:\Python34\Scripts\pip.exe. On 
OS X, it is in /Library/Frameworks/Python.framework/Versions/3.4/bin/pip3. On 
Linux, it is in /usr/bin/pip3. 
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While pip comes automatically installed with Python 3.4 on Windows and 
OS X, you must install it separately on Linux. To install pip3 on Ubuntu or 
Debian Linux, open a new Terminal window and enter sudo apt-get install 
python3-pip. To install pip3 on Fedora Linux, enter sudo yum install python3 
-pip into a Terminal window. You will need to enter the administrator pass- 
word for your computer in order to install this software. 


Installing Third-Party Modules 


Appendix A 


The pip tool is meant to be run from the command line: You pass it the 
command install followed by the name of the module you want to install. 
For example, on Windows you would enter pip install ModuleName, where 
ModuleName is the name of the module. On OS X and Linux, you'll have to 
run pip3 with the sudo prefix to grant administrative privileges to install the 
module. You would need to type sudo pip3 install ModuleName. 

If you already have the module installed but would like to upgrade it 
to the latest version available on PyPI, run pip install -U ModuleName (or pip3 
install -U ModuleName on OS X and Linux). 

After installing the module, you can test that it installed successfully by 
running import ModuleName in the interactive shell. If no error messages are 
displayed, you can assume the module was installed successfully. 

You can install all of the modules covered in this book by running the 
commands listed next. (Remember to replace pip with pip3 if you're on OS X 
or Linux.) 


e pip install send2trash 

e pip install requests 

e pip install beautifulsoup4 

e pip install selenium 

e pip install openpyxl 

e pip install PyPDF2 

e pip install python-docx (install python-docx, not docx) 
e pip install imapclient 

e pip install pyzmail 

e pip install twilio 

e pip install pillow 

e pip install pyobjc-core (on OS X only) 
e pip install pyobjc (on OS X only) 

e pip install python3-xlib (on Linux only) 
e pip install pyautogui 


For OS X users: The pyobjc module can take 20 minutes or longer to install, so don’t 
be alarmed if it takes a while. You should also install the pyobjc-core module first, 
which will reduce the overall installation time. 
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If you have a program open in IDLE’s 
file editor, running it is a simple matter 
of pressing F5 or selecting the Run >» Run 
Module menu item. This is an easy way to run 
programs while writing them, but opening IDLE to 
run your finished programs can be a burden. There 
are more convenient ways to execute Python scripts. 





Shebang Line 
The first line of all your Python programs should be a shebang line, which 


tells your computer that you want Python to execute this program. The she- 
bang line begins with #!, but the rest depends on your operating system. 

e On Windows, the shebang line is #! python3. 

e On OSX, the shebang line is #! /usr/bin/env python3. 

e On Linux, the shebang line is #! /usr/bin/python3. 
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You will be able to run Python scripts from IDLE without the shebang 
line, but the line is needed to run them from the command line. 


Running Python Programs on Windows 


Appendix B 


On Windows, the Python 3.4 interpreter is located at C:\Python34\python.exe. 
Alternatively, the convenient py.exe program will read the shebang line at the 
top of the .py file’s source code and run the appropriate version of Python 
for that script. The py.exe program will make sure to run the Python pro- 
gram with the correct version of Python if multiple versions are installed on 
your computer. 

To make it convenient to run your Python program, create a .bat batch 
file for running the Python program with py.exe. To make a batch file, make 
a new text file containing a single line like the following: 





@py.exe C:\path\to\your\pythonScript.py %* 





Replace this path with the absolute path to your own program, and 
save this file with a .bai file extension (for example, pythonScript.bat). This 
batch file will keep you from having to type the full absolute path for the 
Python program every time you want to run it. I recommend you place 
all your batch and .py files in a single folder, such as C:\MyPythonScripts or 
C.:\Users\YourName\PythonScripts. 

The C:\MyPythonScripts folder should be added to the system path on 
Windows so that you can run the batch files in it from the Run dialog. To 
do this, modify the PATH environment variable. Click the Start button and 
type Edit environment variables for your account. This option should auto- 


complete after yOu ve begun Environment Variables less 
to type it. The Environment 

















Variables window that appears User variables for Al 
will look like Figure B-1. | Variable ii E 
From System variables, PATH C:\Users\Al\AppData\Roaming\npm;C:\... 
: TEMP %USERPROFILE% \AppData\Local\Temp 
select the Path variable and TMP %USERPROFILE%\AppData\Local\Temp | 
click Edit. In the Value text l 
field, append a semicolon, EF EEEE 
. New... ) | Edit... ) [ Delete ) 
type C:\MyPythonScripts, — : 
and then click OK. Now you System variables 
can run any Python scriptin icles ale F 
the C:\MyPythonScripts folder Path C:\Program Files (x86)\Java\jdk1.7.0_5... JF 
PATHEXT -COM;.EXE;.BAT;.CMD;.VBS;.VBE;.JS;.... 


by simply pressing WIN-R and PP22_EXE4]_JA... C:\Program Files (x86)\Java\jre7 
entering the script’s name. PROCESSOR_AR... AMD64 > 
Running pythonScript, for = 


instance, will run pythonScript Laat] [ete (nan | 


.bat, which in turn will save 


you from having to run the | cancel] 

















whole command py.exe C:\ 


MyPythonScripts\pythonScript.py Figure B-1: The Environment Variables window on 
from the Run dialog. Windows 


Running Python Programs on OS X and Linux 


On OS X, selecting Applications > Utilities > Terminal will bring up a 
Terminal window. A Terminal window is a way to enter commands on your 
computer using only text, rather than clicking through a graphic interface. 
To bring up the Terminal window on Ubuntu Linux, press the WIN (or 
SUPER) key to bring up Dash and type in Terminal. 

The Terminal window will begin in the home folder of your user account. 
If my username is asweigart, the home folder will be /Users/asweigart on OS X 
and /home/asweigart on Linux. The tilde (~) character is a shortcut for your 
home folder, so you can enter cd ~ to change to your home folder. You can 
also use the cd command to change the current working directory to any 
other directory. On both OS X and Linux, the pwd command will print the 
current working directory. 

To run your Python programs, save your .py file to your home folder. 
Then, change the .py file’s permissions to make it executable by running 
chmod +x pythonScript.py. File permissions are beyond the scope of this book, 
but you will need to run this command on your Python file if you want to 
run the program from the Terminal window. Once you do so, you will be 
able to run your script whenever you want by opening a Terminal window 
and entering ./pythonScript.py. The shebang line at the top of the script will 
tell the operating system where to locate the Python interpreter. 


Running Python Programs with Assertions Disabled 


You can disable the assert statements in your Python programs for a slight 
performance improvement. When running Python from the terminal, 
include the -0 switch after python or python3 and before the name of the 
.py file. This will run an optimized version of your program that skips the 
assertion checks. 
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ANSWERS TO THE 
PRACTICE QUESTIONS 


This appendix contains the answers to 

the practice problems at the end of each 
chapter. I highly recommend that you take the 

time to work through these problems. Programming 
is more than memorizing syntax and a list of func- 
tion names. As when learning a foreign language, 
the more practice you put into it, the more you will 
get out of it. There are many websites with practice 
programming problems as well. You can find a list of 
these at hitp://nostarch.com/automatestuff/. 
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Chapter 1 


l. 
2. 


10. 


Chapter 2 


Appendix C 


l. 


The operators are +, -, *, and /. The values are 'hello', -88.8, and 5. 


The string is 'spam'; the variable is spam. Strings always start and end 
with quotes. 


The three data types introduced in this chapter are integers, floating- 
point numbers, and strings. 


An expression is a combination of values and operators. All expressions 
evaluate (that is, reduce) to a single value. 


An expression evaluates to a single value. A statement does not. 


The bacon variable is set to 20. The bacon + 1 expression does not reassign 
the value in bacon (that would need an assignment statement: bacon = 
bacon + 1). 


Both expressions evaluate to the string 'spamspamspam'. 
Variable names cannot begin with a number. 


The int(), float(), and str() functions will evaluate to the integer, float- 
ing-point number, and string versions of the value passed to them. 


The expression causes an error because 99 is an integer, and only 
strings can be concatenated to other strings with the + operator. The 
correct way is I have eaten ' + str(99) + ' burritos.'. 


True and False, using capital Tand F, with the rest of the word in 
lowercase 


and, or, and not 


True and True is True. 
True and False is False. 
False and True is False. 
False and False is False. 
True or True is True. 
True or False is True. 
False or True is True. 
False or False is False. 
not True is False. 

not False is True. 


False 
False 
True 
False 
False 
True 


10. 
11. 


12. 


13. 


14. 


==, l=, <, >, <=, and >=. 

== is the equal to operator that compares two values and evaluates to 

a Boolean, while = is the assignment operator that stores a value in a 
variable. 

A condition is an expression used in a flow control statement that evalu- 
ates to a Boolean value. 

The three blocks are everything inside the if statement and the lines 
print(‘bacon') and print(‘ham'). 





print(‘eggs') 
if spam > 5: 
print(‘bacon') 
else: 
print(‘ham' ) 
print(‘spam' ) 





The code: 





if spam == 1: 
print(‘Hello') 

elif spam == 
print(‘Howdy' ) 

else: 
print('Greetings!') 





Press CTRL-C to stop a program stuck in an infinite loop. 


The break statement will move the execution outside and just after a loop. 
The continue statement will move the execution to the start of the loop. 


They all do the same thing. The range(10) call ranges from 0 up to (but 
not including) 10, range(0, 10) explicitly tells the loop to start at 0, and 
range(0, 10, 1) explicitly tells the loop to increase the variable by 1 on 
each iteration. 


The code: 





for i in range(1, 11): 
print(i) 


and: 





i= 1 

while i <= 10: 
print(i) 
i=i+1 





This function can be called with spam.bacon(). 
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Chapter 3 


l. 


10. 
ll. 


12. 
13. 
14. 


Chapter 4 


Appendix C 


l. 


ONO oe 


Functions reduce the need for duplicate code. This makes programs 
shorter, easier to read, and easier to update. 


The code in a function executes when the function is called, not when 
the function is defined. 


The def statement defines (that is, creates) a function. 


A function consists of the def statement and the code in its def clause. 
A function call is what moves the program execution into the function, 
and the function call evaluates to the function’s return value. 


There is one global scope, and a local scope is created whenever a func- 
tion is called. 


When a function returns, the local scope is destroyed, and all the vari- 
ables in it are forgotten. 


A return value is the value that a function call evaluates to. Like any 
value, a return value can be used as part of an expression. 


If there is no return statement for a function, its return value is None. 


A global statement will force a variable in a function to refer to the 
global variable. 


The data type of None is NoneType. 


That import statement imports a module named areallyourpetsnamederic. 
(This isn’t a real Python module, by the way.) 


This function can be called with spam.bacon(). 
Place the line of code that might cause an error in a try clause. 


The code that could potentially cause an error goes in the try clause. 
The code that executes if an error happens goes in the except clause. 


The empty list value, which is a list value that contains no items. This is 
similar to how '' is the empty string value. 


spam[2] = ‘hello’ (Notice that the third value in a list is at index 2 
because the first index is 0.) 


‘d' (Note that '3' * 2 is the string '33', which is passed to int() before 
being divided by 11. This eventually evaluates to 3. Expressions can be 
used wherever values are used.) 


‘d' (Negative indexes count from the end.) 


'a', 'b'] 


[ 
1 
[3.14, 'cat', 11, 'cat', True, 99] 
[3.14, 11, 'cat', True] 
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2. 
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Chapter 6 
1. 


The operator for list concatenation is +, while the operator for replica- 
tion is *. (This is the same as for strings.) 


While append() will add values only to the end of a list, insert() can add 
them anywhere in the list. 


The del statement and the remove() list method are two ways to remove 
values from a list. 


Both lists and strings can be passed to len(), have indexes and slices, be 
used in for loops, be concatenated or replicated, and be used with the 
in and not in operators. 


Lists are mutable; they can have values added, removed, or changed. 

Tuples are immutable; they cannot be changed at all. Also, tuples are 
written using parentheses, ( and ), while lists use the square brackets, 
[ and ]. 

(42,) (The trailing comma is mandatory.) 

The tuple() and list() functions, respectively 

They contain references to list values. 


The copy.copy() function will do a shallow copy of a list, while the 
copy.deepcopy() function will do a deep copy of a list. That is, only copy 
.-deepcopy() will duplicate any lists inside the list. 


Two curly brackets: {} 

{'foo': 42} 

The items stored in a dictionary are unordered, while the items in a list 
are ordered. 

You get a KeyError error. 


There is no difference. The in operator checks whether a value exists as 
a key in the dictionary. 


‘cat' in spam checks whether there is a 'cat' key in the dictionary, while 
‘cat’ in spam.values() checks whether there is a value 'cat' for one of 
the keys in spam. 


spam.setdefault('color', '‘black') 
pprint.pprint() 


Escape characters represent characters in string values that would 
otherwise be difficult or impossible to type into code. 


\nis a newline; \t is a tab. 


The \\ escape character will represent a backslash character. 
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13. 


The single quote in Howl's is fine because you’ve used double quotes to 
mark the beginning and end of the string. 


Multiline strings allow you to use newlines in strings without the \n 
escape character. 


The expressions evaluate to the following: 


e 'e 

e  'Hello' 

e  'Hello' 

e  'lo world! 


The expressions evaluate to the following: 


° 'HELLO' 
e True 
e "hello' 


The expressions evaluate to the following: 

e  ['Remember,', 'remember,', ‘the’, 'fifth', 'of', ‘November. ' ] 
e = 'There-can-be-only-one.' 

The rjust(), ljust(), and center() string methods, respectively 


The lstrip() and rstrip() methods remove whitespace from the left and 
right ends of a string, respectively. 


The re.compile() function returns Regex objects. 

Raw strings are used so that backslashes do not have to be escaped. 
The search() method returns Match objects. 

The group() method returns strings of the matched text. 


Group 0 is the entire match, group 1 covers the first set of parentheses, 
and group 2 covers the second set of parentheses. 


Periods and parentheses can be escaped with a backslash: \., \(, and \). 


If the regex has no groups, a list of strings is returned. If the regex has 
groups, a list of tuples of strings is returned. 


The | character signifies matching “either, or” between two groups. 


The ? character can either mean “ match zero or one of the preceding 
group” or be used to signify nongreedy matching. 


The + matches one or more. The * matches zero or more. 


The {3} matches exactly three instances of the preceding group. The 
{3,5} matches between three and five instances. 

The \d, \w, and \s shorthand character classes match a single digit, 
word, or space character, respectively. 

The \D, \W, and \s shorthand character classes match a single character 
that is not a digit, word, or space character, respectively. 


14. 


15. 


16. 


17. 
18. 
19. 


20. 


21. 
. re.compile(r' (Alice|Bob|Carol)\s(eats | pets |throws)\ 


Chapter 


SUSE re 


Chapter 9 
1. 


Passing re.I or re. IGNORECASE as the second argument to re.compile() will 
make the matching case insensitive. 


The . character normally matches any character except the newline 
character. If re.DOTALL is passed as the second argument to re.compile(), 
then the dot will also match newline characters. 


The .* performs a greedy match, and the .*? performs a nongreedy 
match. 


Either [0-9a-z] or [a-z0-9] 
"X drummers, X pipers, five rings, X hens' 


The re.VERBOSE argument allows you to add whitespace and comments to 
the string passed to re.compile(). 


re.compile(r'*\d{1,3}(,{3})*$') will create this regex, but other regex 
strings can produce a similar regular expression. 


re.compile(r'[A-Z][a-z]*\sNakamoto' ) 


s(apples|cats|baseballs)\.', re. IGNORECASE) 


Relative paths are relative to the current working directory. 
Absolute paths start with the root folder, such as /or C:\. 


The os.getcwd() function returns the current working directory. The 
os.chdir() function changes the current working directory. 


The . folder is the current folder, and .. is the parent folder. 
C:\bacon\eggs is the dir name, while spam.ixt is the base name. 
The string 'r' for read mode, 'w' for write mode, and '‘a' for append mode 


An existing file opened in write mode is erased and completely 
overwritten. 


The read() method returns the file’s entire contents as a single string 
value. The readlines() method returns a list of strings, where each 
string is a line from the file’s contents. 


A shelf value resembles a dictionary value; it has keys and values, along 
with keys() and values() methods that work similarly to the dictionary 
methods of the same names. 


The shutil.copy() function will copy a single file, while shutil.copytree() 
will copy an entire folder, along with all its contents. 


The shutil.move() function is used for renaming files, as well as 
moving them. 
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The send2trash functions will move a file or folder to the recycle bin, 
while shutil functions will permanently delete files and folders. 

The zipfile.ZipFile() function is equivalent to the open() function; the 
first argument is the filename, and the second argument is the mode to 
open the ZIP file in (read, write, or append). 


assert(spam >= 10, 'The spam variable is less than 10.') 


assert(eggs.lower() != bacon.lower(), 'The eggs and bacon variables are 
the same!') or assert(eggs.upper() != bacon.upper(), 'The eggs and bacon 
variables are the same!') 

assert(False, ‘This assertion always triggers.') 


To be able to call logging. debug(), you must have these two lines at the 
start of your program: 





import logging 
logging. basicConfig(level=logging.DEBUG, format=' %(asctime)s - 
%(levelname)s - %(message)s') 





To be able to send logging messages to a file named programLog. txt 
with logging.debug(), you must have these two lines at the start of your 
program: 





import logging 
>>> logging. basicConfig(filename='programLog.txt', level=logging.DEBUG, 
format=" %(asctime)s - %(levelname)s - %(message)s') 





DEBUG, INFO, WARNING, ERROR, and CRITICAL 
logging. disable(logging.CRITICAL) 


You can disable logging messages without removing the logging func- 
tion calls. You can selectively disable lower-level logging messages. You 
can create logging messages. Logging messages provides a timestamp. 
The Step button will move the debugger into a function call. The Over 
button will quickly execute the function call without stepping into it. 
The Out button will quickly execute the rest of the code until it steps 
out of the function it currently is in. 


After you click Go, the debugger will stop when it has reached the end 
of the program or a line with a breakpoint. 

A breakpoint is a setting on a line of code that causes the debugger to 
pause when the program execution reaches the line. 


To set a breakpoint in IDLE, right-click the line and select Set 
Breakpoint from the context menu. 
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10. 
11. 
12. 
13. 
14. 
15. 


16. 


17. 


18. 


The webbrowser module has an open() method that will launch a web 
browser to a specific URL, and that’s it. The requests module can down- 
load files and pages from the Web. The BeautifulSoup module parses 
HTML. Finally, the selenium module can launch and control a browser. 
The requests.get() function returns a Response object, which has a text 
attribute that contains the downloaded content as a string. 

The raise_for_status() method raises an exception if the download had 
problems and does nothing if the download succeeded. 

The status_code attribute of the Response object contains the HTTP 
status code. 

After opening the new file on your computer in 'wb' “write binary” 
mode, use a for loop that iterates over the Response object’s iter_content() 
method to write out chunks to the file. Here’s an example: 





saveFile = open('filename.html', ‘wb') 
for chunk in res.iter_content(100000): 
saveFile.write(chunk) 


F12 brings up the developer tools in Chrome. Pressing CTRL-SHIFT-C 
(on Windows and Linux) or #&-OPTION-C (on OS X) brings up the devel- 
oper tools in Firefox. 


Right-click the element in the page, and select Inspect Element from 
the menu. 


'#main' 

'.highlight' 

‘div div' 

"button[value="favorite" |' 

spam.getText() 

linkElem.attrs 

The selenium module is imported with from selenium import webdriver. 


The find_element_* methods return the first matching element as 

a WebElement object. The find_elements_* methods return a list of all 
matching elements as WebElement objects. 

The click() and send_keys() methods simulate mouse clicks and key- 
board keys, respectively. 

Calling the submit() method on any element within a form submits 
the form. 


The forward(), back(), and refresh() WebDriver object methods simulate 
these browser buttons. 
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1. The openpyxl.load_workbook() function returns a Workbook object. 
The get_sheet_names() method returns a Worksheet object. 

Call wb.get_sheet_by_name('Sheet1'). 

Call wb.get_active_sheet(). 

sheet['C5'].value or sheet.cell(row=5, column=3).value 

sheet['C5'] = ‘Hello’ or sheet.cell(row=5, column=3).value = ‘Hello’ 


cell.row and cell.column 


GO, GUE OY ae HHT OFT 


They return the highest column and row with values in the sheet, 
respectively, as integer values. 


9. openpyxl.cell.column_index_from_string('M') 
10. openpyxl.cell.get_column_letter(14) 

Il. sheet['A1':'F1'] 

12. wb.save(‘example.xlsx’) 


13. A formula is set the same way as any value. Set the cell’s value attribute 
to a string of the formula text. Remember that formulas begin with the 
= sign. 

14. When calling load_workbook(), pass True for the data_only keyword 
argument. 

15. sheet.row_dimensions[5].height = 100 

16. sheet.column_dimensions['C'].hidden = True 


17. OpenPyXL 2.0.5 does not load freeze panes, print titles, images, or 
charts. 


18. Freeze panes are rows and columns that will always appear on the 
screen. They are useful for headers. 


19. openpyxl.charts.Reference(), openpyxl.charts.Series(), openpyxl.charts. 
BarChart(), chartObj.append(seriesObj), and add_chart() 


Chapter 13 


A File object returned from open() 


2. Read-binary (‘rb') for PdfFileReader() and write-binary (‘wb') for 
PdfFileWriter() 


3. Calling getPage(4) will return a Page object for page 5, since page 0 is the 
first page. 


4. The numPages variable stores an integer of the number of pages in the 
PdfFileReader object. 


5. Call decrypt(' swordfish’). 


6. The rotateClockwise() and rotateCounterClockwise() methods. The 
degrees to rotate is passed as an integer argument. 
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docx.Document ('demo.docx' ) 


A document contains multiple paragraphs. A paragraph begins on a 
new line and contains multiple runs. Runs are contiguous groups of 
characters within a paragraph. 


Use doc.paragraphs. 
A Run object has these variables (nota Paragraph). 


True always makes the Run object bolded and False makes it always not 
bolded, no matter what the style’s bold setting is. None will make the Run 
object just use the style’s bold setting. 


Call the docx.Document() function. 
doc.add_paragraph('Hello there!') 
The integers 0, 1, 2, 3, and 4 


In Excel, spreadsheets can have values of data types other than strings; 
cells can have different fonts, sizes, or color settings; cells can have 
varying widths and heights; adjacent cells can be merged; and you can 
embed images and charts. 


You pass a File object, obtained from a call to open(). 


File objects need to be opened in read-binary ('rb') for Reader objects 
and write-binary (‘wb') for Writer objects. 


The writerow() method 


The delimiter argument changes the string used to separate cells 
in a row. The lineterminator argument changes the string used to 
separate rows. 


json. loads() 
json. dumps() 


A reference moment that many date and time programs use. The 
moment is January 1st, 1970, UTC. 


time.time() 
time.sleep(5) 


It returns the closest integer to the argument passed. For example, 
round(2.4) returns 2. 


A datetime object represents a specific moment in time. A timedelta 
object represents a duration of time. 


threadObj = threading. Thread(target=spam) 
thread0bj.start() 
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Make sure that code running in one thread does not read or write the 
same variables as code running in another thread. 


subprocess .Popen('c:\\Windows\\System32\\calc.exe' ) 


SMTP and IMAP, respectively 

smtplib.SMTP(), smtpObj.ehlo(), smptObj.starttls(), and smtp0bj.login() 
imapclient.IMAPClient() and imap0bj.login() 

A list of strings of IMAP keywords, such as 'BEFORE <date>', 'FROM 
<string>’, or 'SEEN' 

Assign the variable imaplib._MAXLINE a large integer value, such as 
10000000. 

The pyzmail module reads downloaded emails. 


You will need the Twilio account SID number, the authentication token 
number, and your Twilio phone number. 


An RGBA value is a tuple of 4 integers, each ranging from 0 to 255. The 
four integers correspond to the amount of red, green, blue, and alpha 
(transparency) in the color. 


A function call to ImageColor.getcolor('CornflowerBlue', 'RGBA') will 
return (100, 149, 237, 255), the RGBA value for that color. 


A box tuple is a tuple value of four integers: the left edge x-coordinate, 
the top edge y-coordinate, the width, and the height, respectively. 


Image. open('zophie.png' ) 
imageObj.size is a tuple of two integers, the width and the height. 


imageObj.crop((0, 50, 50, 50)). Notice that you are passing a box tuple to 
crop(), not four separate integer arguments. 


Call the imageObj.save('new_filename.png') method of the Image object. 
The ImageDraw module contains code to draw on images. 


ImageDraw objects have shape-drawing methods such as point(), line(), 
or rectangle(). They are returned by passing the Image object to the 
ImageDraw.Draw() function. 


Move the mouse to the top-left corner of the screen, that is, the (0, 0) 
coordinates. 


pyautogui.size() returns a tuple with two integers for the width and 
height of the screen. 


pyautogui.position() returns a tuple with two integers for the x- and 
y-coordinates of the mouse cursor. 


The moveTo() function moves the mouse to absolute coordinates on the 
screen, while the moveRel() function moves the mouse relative to the 
mouse’s current position. 


pyautogui.dragTo() and pyautogui.dragRel() 
pyautogui.typewrite('Hello world! ') 


Either pass a list of keyboard key strings to pyautogui.typewrite() (such 
as 'left') or pass a single keyboard key string to pyautogui.press(). 


pyautogui.screenshot('screenshot.png' ) 


pyautogui.PAUSE = 2 
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Symbols 


= (assignment) operator, 18, 34 
\ (backslash), 124, 151, 162, 174-175 
line continuation character, 93 
* (caret symbol), 162 
matching beginning of string, 
159-160 
negative character classes, 159 
: (colon), 38, 45, 54, 82, 127 
{} (curly brackets), 105, 162 
greedy vs. nongreedy matching, 
156-157 
matching specific repetitions 
with, 156 
$ (dollar sign), 159-160, 162 
. (dot character), 160-162 
using in paths, 175-176 
wildcard matches, 160-162 
" (double quotes), 124 
** (exponent) operator, 15 
== (equal to) operator, 33, 34 
/ (forward slash), 174-175 
division operator, 15, 88 
> (greater than) operator, 33 
>= (greater than or equal to) 
operator, 33 
# (hash character), 126 
// (integer division/floored quotient) 
operator, 15 
< (less than) operator, 33 
<= (less than or equal to) operator, 33 
% (modulus/remainder) operator, 
15, 88 
* (multiplication) operator, 15, 83, 88 
!= (not equal to) operator, 33 
() (parentheses), 96-97, 152-153 
| (pipe character), 153-154, 164-165 
+ (plus sign), 155-156, 162 
addition operator, 15, 17, 83, 88 
? (question mark), 154-155, 162 
' (single quote), 124 


[] (square brackets), 80, 162 

* (star), 162 
using with wildcard character, 161 
zero or more matches with, 155 

- (subtraction) operator, 15, 88 

"" (triple quotes), 125, 164 

_ (underscore), 20 


A 


%A directive, 344 
%a directive, 344 
absolute paths, 175-179 
abspath() function, 177 
addition (+) operator, 15, 17, 83, 88 
additive color model, 389 
add_heading() method, 314 
addPage() method, 299 
add_paragraph() method, 313-314 
add_picture() method, 315 
add_run() method, 313-314 
algebraic chess notation, 112-113 
all_caps attribute, 311 
ALL search key, 369 
alpha, defined, 388 
and operator, 35 
ANSWERED search key, 370 
API (application programming 
interface), 327-328 
append() method, 89-90 
application-specific passwords, 365 
args keyword, 349 
arguments, function, 23, 63 
keyword arguments, 65-66 
passing to processes, 354 
passing to threads, 348-349 
assertions, 219-221 
disabling, 445 
assignment (=) operator, 18, 34 
AT&T mail, 363, 367 
attributes, HTML, 241, 248 
augmented assignment operators, 
88-89 


\b backspace escape character, 419 
%B directive, 344 
%b directive, 344 
back() method, 261 
backslash (\), 124, 151, 162, 174-175 
BarChart() function, 290 
basename() function, 178 
BCC search key, 370 
Beautiful Soup, 245. See also bs4 module 
BeautifulSoup objects, 245-246 
BEFORE search key, 369 
binary files, 180-181, 184-185 
binary operators, 35-37 
bitwise or operator, 164-165 
blank strings, 17 
blocking execution, 337 
blocks of code, 37-38 
BODY search key, 369 
bold attribute, 311 
Boolean data type 
binary operators, 35-36 
flow control and, 32-33 
in operator, 87 
not in operator, 87 
“truthy” and “falsey” values, 53 
using binary and comparison 
operators together, 36-37 
box tuples, 390 
breakpoints, debugging using, 229-231 
break statements 
overview, 49-50 
using in for loop, 55 
browser, opening using webbrowser 
module, 234-236 
bs4 module 
creating object from HTML, 
245-246 
finding element with select() 
method, 246-247 
getting attribute, 248 
overview, 245 
built-in functions, 57 
bulleted list, creating in Wiki markup, 
139-141 
copying and pasting clipboard, 
139-140 
joining modified lines, 141 
overview, 139 
separating lines of text, 140 


C 


calling functions, 23 
call stack, defined, 217 
camelcase, 21 
caret symbol (^), 162 
matching beginning of string, 
159-160 
negative character classes, 159 
Cascading Style Sheets (CSS) 
matching with selenium 
module, 258 
selectors, 246-247 
case sensitivity, 21, 163 
CC search key, 370 
Cell objects, 268-269 
cells, in Excel spreadsheets, 266 
accessing Cell object by its name, 
268-269 
merging and unmerging, 286-287 
writing values to, 278-279 
center() method, 133-134, 426 
chaining method calls, 398 
character classes, 158-159, 162 
character styles, 310 
charts, Excel, 288-290 
chdir() function, 175 
Chrome, developer tools in, 242-243 
clear() method, 258 
click() function, 420, 430, 431 
clicking mouse, 420 
click() method, 259 
clipboard, using string from, 236 
CMYK color model, 389 
colon (:), 38, 45, 54, 82, 127 
color values 
CMYK vs. RGB color models, 389 
RGBA values, 388-389 
column_index_from_string() function, 270 
columns, in Excel spreadsheets 
setting height and width of, 
285-286 
slicing Worksheet objects to get Cell 
objects in, 270-272 
Comcast mail, 363, 367 
comma-delimited items, 80 
command line arguments, 235 
commentAfterDelay() function, 429 
comments 
multiline, 126 
overview, 23 


comparison operators 
overview, 33-35 
using binary operators with, 36-37 
compile() function, 151, 152, 164-165 
compressed files 
backing up folder into, 209-212 
creating ZIP files, 205-206 
extracting ZIP files, 205 
overview, 203-204 
reading ZIP files, 204 
computer screen 
coordinates of, 415 
resolution of, 416 
concatenation 
of lists, 83 
string, 17-18 
concurrency issues, 349 
conditions, defined, 37 
continue statements 
overview, 50-53 
using in for loop, 55 
Coordinated Universal Time (UTC), 336 
coordinates 
of computer screen, 415 
of an image, 389-390 
copy() function, 100-101, 135, 198, 394 
copytree() function, 198-199 
countdown project, 357-358 
counting down, 357 
overview, 357 
playing sound file, 357-358 
cProfile.run() function, 337 
crashes, program, 14 
create_sheet() method, 278 
CRITICAL level, 224 
cron, 354 
cropping images, 393-394 
CSS (Cascading Style Sheets) 
matching with selenium module, 258 
selectors, 246-247 
CSV files 
defined, 319 
delimeter for, 324 
format overview, 320 
line terminator for, 324 
Reader objects, 321 
reading data in loop, 322 
removing header from, 324-327 
looping through CSV files, 325 
overview, 324-325 
reading in CSV file, 325-326 
writing out CSV file, 326-327 
Writer objects, 322-323 


curly brackets ({}), 105, 162 
greedy vs. nongreedy matching, 
156-157 
matching specific repetitions 
with, 156 
current working directory, 175 


\D character class, 158 

\d character class, 158 

%d directive, 344 

data structures 
algebraic chess notation, 112-113 
tic-tac-toe board, 113-117 


data types 
Booleans, 32 
defined, 16 


dictionaries, 105-106 
floating-point numbers, 17 
integers, 17 
list() function, 97 
lists, 80 
mutable vs. immutable, 94-96 
None value, 65 
strings, 17 
tuple() function, 97 
tuples, 96-97 
datetime module 
arithmetic using, 343 
converting objects to strings, 
344-345 
converting strings to objects, 345 
fromtimestamp() function, 341 
now() function, 341 
overview, 341-342, 346 
pausing program until time, 344 
timedelta data type, 342-343 
total_seconds() method, 342 
datetime objects, 341-342 
converting to strings, 344-345 
converting from strings to, 345 
debug() function, 222 
debugging 
assertions, 219-221 
defined, 4 
getting traceback as string, 217-218 
in IDLE 
overview, 225-227 
stepping through program, 
227-229 
using breakpoints, 229-231 
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debugging (continued) 
logging 
disabling, 224-225 
to file, 225 
levels of, 223-224 
logging module, 221-223 
print() function and, 223 
raising exceptions, 216-217 
DEBUG level, 223 
decimal numbers. See floating-point 
numbers 
decode() method, 374-375 
decryption, of PDF files, 297-298 
deduplicating code, 62 
deepcopy() function, 100-101 
def statements, 62 
with parameters, 63 
DELETED search key, 370 
delete_messages() method, 375 
deleting files/folders 
permanently, 200-201 
using send2trash module, 201-202 
del statements, 84 
dictionaries 
copy() function, 100-101 
deepcopy() function, 100-101 
get() method, 109 
in operator, 109 
items() method, 107-108 
keys() method, 107-108 
lists vs., 106-107 
nesting, 117-119 
not in operator, 109 
overview, 105-106 
setdefault() method, 110-111 
values() method, 107-108 
directories 
absolute vs. relative paths, 175-176 
backslash vs. forward slash, 174-175 
copying, 198-199 
creating, 176 
current working directory, 175 
defined, 173-174 
deleting permanently, 200-201 
deleting using send2trash module, 
201-202 
moving, 199-200 
os.path module 
absolute paths in, 177-179 
file sizes, 179-180 
folder contents, 179-180 
overview, 177 


path validity, 180 
relative paths in, 177-179 

renaming, 199-200 

walking, 202-203 
dirname() function, 178 
disable() function, 224 
division (/) operator, 15, 88 
Document objects, 307-308 
dollar sign ($), 159-160, 162 
dot character (.), 160-162 

using in paths, 175-176 

wildcard matches, 160-162 
dot-star character (.*), 161 
doubleClick() function, 420, 430 
double quotes ("), 124 
double_strike attribute, 311 
downloading 

files from web, 239-240 

web pages, 237-238 

XKCD comics, 251-256, 350-352 
DRAFT search key, 370 
dragging mouse, 420-422 
dragRel() function, 420, 422, 430 
dragTo() function, 420, 430 
drawing on images 

ellipses, 407 

example program, 407-408 

ImageDraw module, 406 

lines, 406-407 

points, 406 

polygons, 407 

rectangles, 407 

text, 408-410 
dumps() function, 329 
duration keyword arguments, 416 


ehlo() method, 364, 379 

elements, HTML, 240 

elif statements, 40-45 

ellipse() method, 407 

else statements, 39-40 

email addresses, extracting, 165-169 
creating regex, 166-167 
finding matches on clipboard, 

167-168 

joining matches into a string, 168 
overview, 165-166 

emails 
deleting, 375 
disconnecting from server, 375-376 
fetching 


folders, 368-369 
getting message content, 
372-373 
logging into server, 368 
overview, 366-367 
raw messages, 373-375 
gmail search() method, 372 
IMAP, 366 
marking message as read, 372-373 
searching, 368-371 
sending 
connecting to SMTP server, 
363-364 
disconnecting from server, 366 
logging into server, 364-365 
overview, 362 
reminder, 376-380 
sending “hello” message, 364 
sending message, 365 
TLS encryption, 364 
SMTP, 362 
emboss attribute, 311 
encryption, of PDF files, 302-303 
endswith() method, 131 
epoch timestamps, 336, 341, 346 
equal to (==) operator, 33, 34 
ERROR level, 224 
errors 
crashes and, 14 
help for, 8-9 
escape characters, 124-125 
evaluation, defined, 14 
Excel spreadsheets 
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extensions, file, 173 
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file management (continued) 
compressed files (continued) 
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creating directories, 176 
current working directory, 175 
multiclipboard project, 191-193 
opening files, 181-182 
os.path module 
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path validity, 180 
relative paths in, 177-179 
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dragging mouse, 420-422 
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overview, 8 
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if statements 
overview, 38-39 
using in while loop, 46-47 
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cropping, 393-394 
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Protocol) 
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imapclient module, 366 
IMAPClient objects, 367-368 
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importing modules 
overview, 57-58 
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input() function 
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installing 
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operator, 15 
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isdir() function, 180 

is_displayed() method, 258 

is_enabled() method, 258 

isfile() function, 180 

islower() method, 128-129 

is_selected() method, 258 

isspace() method, 130 

istitle() method, 130 

isupper() method, 128-129 
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keyboard 
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hotkey combinations, 429 
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sending string from keyboard, 
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key names, 427-428 
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launching programs 
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opening files with default 
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passing command line arguments 
to processes, 354 
poll() method, 353 
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scheduling, 354-355 
sleep() function, 355 
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line breaks, Word document, 315 
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line() method, 406-407 
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Linux 
backslash vs. forward slash, 174-175 
cron, 354 
installing Python, 7 
installing third-party modules, 442 
launching processes from 
Python, 353 
logging out of automation 
program, 414 
opening files with default 
applications, 355 
pip tool on, 441-442 
Python support, 4 
running Python programs on, 445 
starting IDLE, 8 
Unix philosophy, 356 
listdir() function, 179 
list_folders() method, 368-369 
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lists 
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not in operator, 87 
overview, 80 
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using lists with, 86 
while loop, 45-49 
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handling command line argument, 
235-236 
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overview, 234 
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mergePage() method, 302 
Message objects, 381-382 
methods 
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sort() method, 91-92 
string 
center() method, 133-134 
copy() method, 135 
endswith() method, 131 


isalnum() method, 129-131 
isalpha() method, 129-130 
isdecimal() method, 129-131 
islower() method, 128-129 
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dragging mouse, 420-422 
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locating, 417-419 
getting coordinates, 418-419 
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exception, 418 
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mouse.position() function, 418 
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moveTo() function, 416, 420, 430 
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os.path module 
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rotating images, 398-399 
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417-419 
putpixel() method, 400 
pyautogui.click() function, 431 
pyautogui.click() method, 420 
pyautogui.doubleClick() function, 420 
pyautogui.dragTo() function, 420 
pyautogui.FailSafeException 
exception, 415 
pyautogui.hotkey() function, 429 
pyautogui.keyDown() function, 428 
pyautogui.keyUp() function, 428 
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pyautogui module 
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controlling keyboard, 426-429 
hotkey combinations, 429 
key names, 427—428 
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428-429 
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426-427 
controlling mouse, 415-417, 
419-423 
clicking mouse, 420 
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scrolling mouse, 422-423 
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importing, 417 
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screenshots, 423-424 
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encrypting PDFs, 302-303 
extracting text from PDFs, 296-297 
format overview, 295-296 
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copying, 299-300 
overlaying, 301-302 
rotating, 300-301 
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Python 
data types, 16-17 
downloading, 6 
example program, 21-22 
help, 8-9 
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interactive shell, 8 
interpreter, defined, 7 
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overview, 4 
programming overview, 3 
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python-docx module, 306 
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zero or more matches, 155 
HTML and, 243 
matching with, 151-152 
multiple arguments for compile() 
function, 164-165 
nongreedy matching, 157 
patterns for, 150 
spreading over multiple lines, 164 
substituting strings using, 163-164 
symbol reference, 162 
wildcard character, 160-162 
relative paths, 175-179 
relpath() function, 177, 178 
remainder/modulus (%) operator, 15, 88 
remove() method, 90-91 
remove_sheet() method, 278 
renaming files/folders, 199-200 
date styles, 206-209 
creating regex for dates, 206 
identifying dates in filenames, 
207-208 


overview, 206 
renaming files, 209 

replication 

of lists, 83 

string, 18 
requests module 

downloading files, 239-240 

downloading pages, 237-238 
resolution of computer screen, 416 
Response objects, 237-238 
return values, function, 63-65 
reverse keyword, 91 
RGBA values, 388-389 
RGB color model, 389 
vightClick() function, 420, 430 
rjust() method, 133-134, 419 
rmdir() function, 200 
rmtree() function, 200 
rotateClockwise() method, 300 
rotateCounterClockwise() method, 300 
rotating images, 398-399 
rounding numbers, 338 
rows, in Excel spreadsheets 

setting height and width of, 285-286 

slicing Worksheet objects to get 

Cell objects in, 270-272 

rstrip() method, 134-135 
rtl attribute, 311 
Run objects, 310, 311-312 
running programs 

on Linux, 445 

on OS X, 445 

overview, 443 

on Windows, 444-445 

shebang line, 443-444 
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\S character class, 158 

\s character class, 158 

%S directive, 344 

Safari, developer tools in, 243 
save() method, 391 


scope 
global, 70-71 
local, 67-70 


screenshot() function, 423, 430 
screenshots 
analyzing, 424 
getting, 423 
scripts 
running from Python program, 355 
running outside of IDLE, 136 
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scroll() function, 422, 423, 430 
scrolling mouse, 422-423 
searching 
email, 368-371 
the Web, 248-251 
finding results, 249-250 
getting command line 
arguments, 249 
opening web browser for 
results, 250-251 
overview, 248 
requesting search page, 249 
search() method, 151 
SEEN search key, 370 
see program, 355 
select_folder() method, 369 
select lists, 435-436 
select() method, bs4 module, 246-247 
selectors, CSS, 246-247, 258 
selenium module 
clicking buttons, 261 
finding elements, 257-259 
following links, 259 
installing, 256 
sending special keystrokes, 260-261 
submitting forms, 259-260 
using Firefox with, 256-257 
send2trash module, 201-202 
sending reminder emails, 376-379 
finding unpaid members, 378 
opening Excel file, 376-377 
overview, 376 
sending emails, 378-379 
send_keys() method, 259-260 
sendmail() method, 365, 379 
sequence numbers, 373 
sequences, 86 
setdefault() method, 110-111 
shadow attribute, 311 
shebang line, 443-444 
shelve module, 184-185 
Short Message Service (SMS) 
sending messages, 381-382 
Twilio service, 380 
shutil module 
deleting files/folders, 200-201 
moving files/folders, 199-200 
renaming files/folders, 199-200 
SID (string ID), 382 
Simple Mail Transfer Protocol. See 
SMTP (Simple Mail 
Transfer Protocol) 


SINCE search key, 369 
single quote ('), 124 
single-threaded programs, 347 
size() function, 416 
sleep() function, 337-338, 344, 346, 355 
slices 
getting sublists with, 82-83 
for strings, 126-127 
small_caps attribute, 311 
SMALLER search key, 370 
SMS (Short Message Service) 
sending messages, 381-382 
Twilio service, 380 
SMTP (Simple Mail Transfer Protocol) 
connecting to server, 363-364 
defined, 362 
disconnecting from server, 366 
logging into server, 364—365 
sending “hello” message, 364 
sending message, 365 
TLS encryption, 364 
SMTP objects, 363-364 
sort() method, 91-92 
sound files, playing, 357-358 
source code, defined, 3 
split() method, 131-133, 178, 320 
spreadsheets. See Excel spreadsheets 
square brackets [], 80 
Stack Overflow, 9 
standard library, 57 
star (*), 161, 162 
using with wildcard character, 161 
zero or more matches with, 155 
start() method, 348, 349, 351 
start program, 355 
startswith() method, 131 
starttls() method, 364, 379 
step argument, 56 
stopwatch project, 338-340 
overview, 338-339 
set up, 339 
tracking lap times, 339-340 
strftime() function, 344-345, 346 
str() function, 25-28, 97, 419 
strike attribute, 311 
string ID (SID), 382 
strings 
center() method, 133-134 
concatenation, 17-18 
converting datetime objects to, 
344-345 
converting to datetime objects, 345 


copying and pasting, 135 
double quotes for, 124 
endswith() method, 131 
escape characters, 124-125 
extracting PDF text as, 296-297 
getting traceback as, 217-218 
indexes for, 126-127 
in operator, 127 
isalnum() method, 129-131 
isalpha() method, 129-130 
isdecimal() method, 129-131 
islower() method, 128-129 
isspace() method, 130 
istitle() method, 130 
isupper() method, 128-129 
join() method, 131-132 
literals, 124 
ljust() method, 133-134 
lower() method, 128-129 
lstrip() method, 134-135 
multiline, 125-126 
mutable vs. immutable data types, 
94-96 
not in operator, 127 
overview, 17 
raw, 125 
replication of, 18 
rjust() method, 133-134 
rstrip() method, 134-135 
slicing, 126-127 
split() method, 131-133 
startswith() method, 131 
strip() method, 134-135 
substituting using regular 
expressions, 163-164 
upper() method, 128-129 
strip() method, 134-135 
strptime() function, 345, 346 
strs, 17, See also strings 
Style objects, 282-283 
SUBJECT search key, 369 
sublists, getting with slices, 82-83 
sub() method, 163-164 
submitButtonColor variable, 432, 435 
submitButton variable, 432 
submit() method, 260 
subprocess module, 335, 352-354 
subtraction (-) operator, 15, 88 
subtractive color model, 389 
Sudoku puzzles, 4 
sys.exit() function, 58 
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tag_name attribute, 258 
Tag objects, 246-247 
tags, HTML, 240 
Task Scheduler, 354 
termination, program, 22, 58 
text attribute, 308, 311 
text messaging 
automatic notifications, 383 
sending messages, 381-382 
Twilio service, 380 
text() method, 408-410 
TEXT search key, 369 
textsize() method, 409 
third-party modules, installing, 
441-442 
Thread() function, 347-348, 351 
threading module, 335, 347 
Thread objects, 347-348 
threads 
concurrency issues, 349 
join() method, 352 
multithreading, 347-348 
image downloader, 350-352 
passing arguments to, 348-349 
processes vs., 352 
tic-tac-toe board, 113-117 
timedelta data type, 342-343, 346 
timedelta objects, 342-343 
time module 
overview, 346 
sleep() function, 337-338, 344 
stopwatch project, 338-340 
time() function, 336-337 
TLS encryption, 364 
top-level domains, 167 
TO search key, 370 
total_seconds() method, 342, 346 
traceback, getting from error, 217-218 
transparency, 388, 397 
transpose() method, 399 
triple quotes ('''), 125, 164 
truetype() function, 409 
truth tables, 35-36 
“truthy” values, 53 
tuple data type 
overview, 96-97 
tuple() function, 97 
twilio module, 380 
TwilioRestClient objects, 381 
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Twilio service 
automatic text messages, 383 
overview, 380 
sending text messages, 381-382 
TypeError, 81, 94 
typewrite() function, 426, 427, 430, 431, 
435, 436 
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Ubuntu, 7 
cron, 354-355 
launching processes from 
Python, 353 
opening files with default 
applications, 355 
Unix philosophy, 356 
UNANSWERED search key, 370 
UNDELETED search key, 370 
underline attribute, 311 
underscore (_), 20 
UNDRAFT search key, 370 
UNFLAGGED search key, 370 
Unicode encodings, 239 
Unix epoch, 336, 341, 346 
Unix philosophy, 356 
unlink() function, 200 
UNSEEN search key, 370 
upper() method, 128-129 
UTC (Coordinated Universal 
Time), 336 
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ValueError, 88, 345 
values, defined, 14, 150 
values() method, 107-108 
variables. See also lists 
assignment statements, 18—19 
defined, 18 
global, 70—71 
initializing, 19 
local, 67—70 
naming, 20-21 
None value and, 65 
overwriting, 19-20 
references, 97—99 
saving with shelve module, 184-185 
storing as list, 84-85 
Verizon mail, 363, 367 
volumes, defined, 174 
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\W character class, 158 
\w character class, 158 
dw directive, 344 
walk() function, 202-203, 354 
WARNING level, 223 
weather data, fetching, 329-332 
downloading JSON data, 330-331 
getting location, 330 
loading JSON data, 331-332 
overview, 329 
webbrowser module 
open() function, 355 
opening browser using, 234-236 
WebDriver objects, 257 
WebElement objects, 257-258 
web scraping 
bs4 module 
creating object from HTML, 
245-246 
finding element with select() 
method, 246-247 
getting attribute, 248 
overview, 245 
downloading 
files, 239-240 
images, 251-256 
pages, 237-238 
and Google maps project, 234-236 
and Google search project, 248-251 
HTML 
browser developer tools and, 
242-243 
finding elements, 244 
learning resources, 240 
overview, 240-241 
viewing page source, 241-242 
overview, 233-234 
requests module, 237-238 
selenium module 
clicking buttons, 261 
finding elements, 257-259 
following links, 259 
installing, 256 
sending special keystrokes, 
260-261 
submitting forms, 259-260 
using Firefox with, 256-257 
websites, opening from script, 355 


while loops 
getting and printing mouse 
coordinates using, 418 
infinite, 418 
overview, 45-49 
whitespace, removing, 134-135 
wildcard character (.), 160-162 
Windows OS 
backslash vs. forward slash, 174-175 
installing Python, 6-7 
installing third-party modules, 442 
launching processes from 
Python, 353 
logging out of automation 
program, 414 
opening files with default 
applications, 355-356 
pip tool on, 441-442 
Python support, 4 
running Python programs on, 
444-445 
starting IDLE, 7 
Task Scheduler, 354 
Word documents 
adding headings, 314-315 
creating documents with 
nondefault styles, 310-311 
format overview, 306-307 
getting text from, 308-309 
line/page breaks, 315 
pictures in, 315-316 
python-docx module, 306 
reading, 307-308 
Run object attributes, 311-312 
styling paragraphs, 309-310 
writing to file, 312-314 
Workbook objects, 267 
workbooks, Excel, 266 
creating worksheets, 278 
deleting worksheets, 278 
opening, 267 
saving, 277 
Worksheet objects, 268 
write() method, 183-184 
Writer objects, 322-323 
writerow() method, 323 
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XKCD comics 
downloading project, 251-256 
designing program, 252-253 
downloading web page, 
253-254 
overview, 251-252 
saving image, 255-256 
multithreaded downloading 
project, 350-352 
creating and starting threads, 
351-352 
using downloadxXkcd() function, 
350-351 
waiting for threads to end, 352 
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%Y directive, 344 
%y directive, 344 
Yahoo! Mail, 363, 367 
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zipfile module 
creating ZIP files, 205-206 
extracting ZIP files, 205 
and folders, 209-212 
overview, 203-204 
reading ZIP files, 204 
ZipFile objects, 204-205 
ZipInfo objects, 204 
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